SGI Freeware 1999 August/SGI Freeware 1999 August.iso/dist/fw_perl.idb/usr/freeware/catman/p_man/cat3/CGI.Z/CGI

Text File | 1998-10-28 | 138.4 KB | 3,763 lines

     CCCCGGGGIIII((((3333))))         22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))        CCCCGGGGIIII((((3333))))



     NNNNAAAAMMMMEEEE
      CGI -    Simple Common Gateway Interface    Class

     SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
        # CGI script that creates a    fill-out form
        # and echoes back its values.

        use    CGI qw/:standard/;
        print header,
          start_html('A    Simple Example'),
          h1('A    Simple Example'),
          start_form,
          "What's your name? ",textfield('name'),p,
          "What's the combination?", p,
          checkbox_group(-name=>'words',
                 -values=>['eenie','meenie','minie','moe'],
                 -defaults=>['eenie','minie']),    p,
          "What's your favorite    color? ",
          popup_menu(-name=>'color',
                 -values=>['red','green','blue','chartreuse']),p,
          submit,
          end_form,
          hr;

         if    (param()) {
         print "Your name is",em(param('name')),p,
               "The keywords are: ",em(join(", ",param('words'))),p,
               "Your favorite color is ",em(param('color')),
               hr;
         }


     AAAABBBBSSSSTTTTRRRRAAAACCCCTTTT
      This perl library uses perl5 objects to make it easy to
      create Web fill-out forms and    parse their contents.  This
      package defines CGI objects, entities    that contain the
      values of the    current    query string and other state
      variables.  Using a CGI object's methods, you    can examine
      keywords and parameters passed to your script, and create
      forms    whose initial values are taken from the    current    query
      (thereby preserving state information).  The module provides
      shortcut functions that produce boilerplate HTML, reducing
      typing and coding errors. It also provides functionality for
      some of the more advanced features of    CGI scripting,
      including support for    file uploads, cookies, cascading style
      sheets, server push, and frames.

      CGI.pm also provides a simple    function-oriented programming
      style    for those who don't need its object-oriented features.

      The current version of CGI.pm    is available at




     Page 1                        (printed 10/23/98)






     CCCCGGGGIIII((((3333))))         22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))        CCCCGGGGIIII((((3333))))



        http://www.genome.wi.mit.edu/ftp/pub/software/WWW/cgi_docs.html
        ftp://ftp-genome.wi.mit.edu/pub/software/WWW/


     DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
      PPPPRRRROOOOGGGGRRRRAAAAMMMMMMMMIIIINNNNGGGG SSSSTTTTYYYYLLLLEEEE

      There    are two    styles of programming with CGI.pm, an object-
      oriented style and a function-oriented style.     In the
      object-oriented style    you create one or more CGI objects and
      then use object methods to create the    various    elements of
      the page.  Each CGI object starts out    with the list of named
      parameters that were passed to your CGI script by the
      server.  You can modify the objects, save them to a file or
      database and recreate    them.  Because each object corresponds
      to the "state" of the    CGI script, and    because    each object's
      parameter list is independent    of the others, this allows you
      to save the state of the script and restore it later.

      For example, using the object    oriented style,    here is    now
      you create a simple "Hello World" HTML page:

         #!/usr/local/bin/pelr
         use CGI;                  # load CGI routines
         $q    = new CGI;              # create new CGI object
         print $q->header,              # create the HTTP header
           $q->start_html('hello world'), # start the HTML
           $q->h1('hello world'),      # level 1 header
           $q->end_html;          # end    the HTML

      In the function-oriented style, there    is one default CGI
      object that you rarely deal with directly.  Instead you just
      call functions to retrieve CGI parameters, create HTML tags,
      manage cookies, and so on.  This provides you    with a cleaner
      programming interface, but limits you    to using one CGI
      object at a time.  The following example prints the same
      page,    but uses the function-oriented interface.  The main
      differences are that we now need to import a set of
      functions into our name space    (usually the "standard"
      functions), and we don't need    to create the CGI object.

         #!/usr/local/bin/pelr
         use CGI qw/:standard/;          #    load standard CGI routines
         print header,              #    create the HTTP    header
           start_html('hello world'), #    start the HTML
           h1('hello world'),          #    level 1    header
           end_html;              #    end the    HTML

      The examples in this document    mainly use the object-oriented
      style.  See HOW TO IMPORT FUNCTIONS for important
      information on function-oriented programming in CGI.pm




     Page 2                        (printed 10/23/98)






     CCCCGGGGIIII((((3333))))         22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))        CCCCGGGGIIII((((3333))))



      CCCCAAAALLLLLLLLIIIINNNNGGGG CCCCGGGGIIII....PPPPMMMM RRRROOOOUUUUTTTTIIIINNNNEEEESSSS

      Most CGI.pm routines accept several arguments, sometimes as
      many as 20 optional ones!  To    simplify this interface, all
      routines use a named argument    calling    style that looks like
      this:

         print $q->header(-type=>'image/gif',-expires=>'+3d');

      Each argument    name is    preceded by a dash.  Neither case nor
      order    matters    in the argument    list.  -type, -Type, and -TYPE
      are all acceptable.  In fact,    only the first argument    needs
      to begin with    a dash.     If a dash is present in the first
      argument, CGI.pm assumes dashes for the subsequent ones.

      You don't have to use    the hyphen at allif you    don't want to.
      After    creating a CGI object, call the    uuuusssseeee____nnnnaaaammmmeeeedddd____ppppaaaarrrraaaammmmeeeetttteeeerrrrssss(((())))
      method with a    nonzero    value.    This will tell CGI.pm that you
      intend to use    named parameters exclusively:

         $query = new CGI;
         $query->use_named_parameters(1);
         $field = $query->radio_group('name'=>'OS',
                      'values'=>['Unix','Windows','Macintosh'],
                      'default'=>'Unix');

      Several routines are commonly    called with just one argument.
      In the case of these routines    you can    provide    the single
      argument without an argument name.  _h_e_a_d_e_r() happens to be
      one of these routines.  In this case,    the single argument is
      the document type.

         print $q->header('text/html');

      Other    such routines are documented below.

      Sometimes named arguments expect a scalar, sometimes a
      reference to an array, and sometimes a reference to a    hash.
      Often, you can pass any type of argument and the routine
      will do whatever is most appropriate.     For example, the
      _p_a_r_a_m() routine is used to set a CGI parameter to a single
      or a multi-valued value.  The    two cases are shown below:

         $q->param(-name=>'veggie',-value=>'tomato');
         $q->param(-name=>'veggie',-value=>'[tomato','tomahto','potato','potahto']);

      A large number of routines in    CGI.pm actually    aren't
      specifically defined in the module, but are generated
      automatically    as needed.  These are the "HTML    shortcuts,"
      routines that    generate HTML tags for use in dynamically-
      generated pages.  HTML tags have both    attributes (the
      attribute="value" pairs within the tag itself) and contents



     Page 3                        (printed 10/23/98)






     CCCCGGGGIIII((((3333))))         22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))        CCCCGGGGIIII((((3333))))



      (the part between the    opening    and closing pairs.)  To
      distinguish between attributes and contents, CGI.pm uses the
      convention of    passing    HTML attributes    as a hash reference as
      the first argument, and the contents,    if any,    as any
      subsequent arguments.     It works out like this:

         Code                Generated HTML
         ----                --------------
         h1()                <H1>
         h1('some','contents');        <H1>some contents</H1>
         h1({-align=>left});        <H1    ALIGN="LEFT">
         h1({-align=>left},'contents'); <H1    ALIGN="LEFT">contents</H1>

      HTML tags are    described in more detail later.

      Many newcomers to CGI.pm are puzzled by the difference
      between the calling conventions for the HTML shortcuts,
      which    require    curly braces around the    HTML tag attributes,
      and the calling conventions for other    routines, which    manage
      to generate attributes without the curly brackets.  Don't be
      confused.  As    a convenience the curly    braces are optional in
      all but the HTML shortcuts.  If you like, you    can use    curly
      braces when calling any routine that takes named arguments.
      For example:

         print $q->header( {-type=>'image/gif',-expires=>'+3d'} );

      If you use the ----wwww switch, you    will be    warned that some
      CGI.pm argument names    conflict with built-in Perl functions.
      The most frequent of these is    the -values argument, used to
      create multi-valued menus, radio button clusters and the
      like.     To get    around this warning, you have several choices:

     example, -value is    an alias for -values.
      1. Use another name for the argument,    if one is available.  For

      2. Change the    capitalization,    e.g. -Values

      3. Put quotes    around the argument name, e.g. '-values'

      Many routines    will do    something useful with a    named argument
      that it doesn't recognize.  For example, you can produce
      non-standard HTTP header fields by providing them as named
      arguments:

        print $q->header(-type  =>    'text/html',
                 -cost  =>    'Three smackers',
                 -annoyance_level => 'high',
                 -complaints_to   => 'bit bucket');

      This will produce the    following nonstandard HTTP header:




     Page 4                        (printed 10/23/98)






     CCCCGGGGIIII((((3333))))         22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))        CCCCGGGGIIII((((3333))))



         HTTP/1.0 200 OK
         Cost: Three smackers
         Annoyance-level: high
         Complaints-to: bit    bucket
         Content-type: text/html

      Notice the way that underscores are translated automatically
      into hyphens.     HTML-generating routines perform a different
      type of translation.

      This feature allows you to keep up with the rapidly changing
      HTTP and HTML    "standards".

      CCCCRRRREEEEAAAATTTTIIIINNNNGGGG AAAA NNNNEEEEWWWW QQQQUUUUEEEERRRRYYYY OOOOBBBBJJJJEEEECCCCTTTT ((((OOOOBBBBJJJJEEEECCCCTTTT----OOOORRRRIIIIEEEENNNNTTTTEEEEDDDD SSSSTTTTYYYYLLLLEEEE))))::::

           $query =    new CGI;

      This will parse the input (from both POST and    GET methods)
      and store it into a perl5 object called $query.

      CCCCRRRREEEEAAAATTTTIIIINNNNGGGG AAAA NNNNEEEEWWWW QQQQUUUUEEEERRRRYYYY OOOOBBBBJJJJEEEECCCCTTTT FFFFRRRROOOOMMMM AAAANNNN IIIINNNNPPPPUUUUTTTT FFFFIIIILLLLEEEE

           $query =    new CGI(INPUTFILE);

      If you provide a file    handle to the _n_e_w() method, it will
      read parameters from the file    (or STDIN, or whatever).  The
      file can be in any of    the forms describing below under
      debugging (i.e. a series of newline delimited    TAG=VALUE
      pairs    will work).  Conveniently, this    type of    file is
      created by the _s_a_v_e()    method (see below).  Multiple records
      can be saved and restored.

      Perl purists will be pleased to know that this syntax
      accepts references to    file handles, or even references to
      filehandle globs, which is the "official" way    to pass    a
      filehandle:

          $query = new CGI(\*STDIN);

      You can also initialize the CGI object with a    FileHandle or
      IO::File object.

      If you are using the function-oriented interface and want to
      initialize CGI state from a file handle, the way to do this
      is with rrrreeeessssttttoooorrrreeee____ppppaaaarrrraaaammmmeeeetttteeeerrrrssss(((()))).     This will (re)initialize the
      default CGI object from the indicated    file handle.

          open (IN,"test.in") || die;
          restore_parameters(IN);
          close IN;

      You can also initialize the query object from    an associative



     Page 5                        (printed 10/23/98)






     CCCCGGGGIIII((((3333))))         22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))        CCCCGGGGIIII((((3333))))



      array    reference:

          $query = new CGI(    {'dinosaur'=>'barney',
                 'song'=>'I love you',
                 'friends'=>[qw/Jessica    George Nancy/]}
                  );

      or from a properly formatted,    URL-escaped query string:

          $query = new CGI('dinosaur=barney&color=purple');

      or from a previously existing    CGI object (currently this
      clones the parameter list, but none of the other object-
      specific fields, such    as autoescaping):

          $old_query = new CGI;
          $new_query = new CGI($old_query);

      To create an empty query, initialize it from an empty    string
      or hash:

         $empty_query = new    CGI("");

         -or-

         $empty_query = new    CGI({});


      FFFFEEEETTTTCCCCHHHHIIIINNNNGGGG AAAA LLLLIIIISSSSTTTT OOOOFFFF KKKKEEEEYYYYWWWWOOOORRRRDDDDSSSS FFFFRRRROOOOMMMM TTTTHHHHEEEE QQQQUUUUEEEERRRRYYYY::::

           @keywords = $query->keywords

      If the script    was invoked as the result of an    <ISINDEX>
      search, the parsed keywords can be obtained as an array
      using    the _k_e_y_w_o_r_d_s() method.

      FFFFEEEETTTTCCCCHHHHIIIINNNNGGGG TTTTHHHHEEEE NNNNAAAAMMMMEEEESSSS OOOOFFFF    AAAALLLLLLLL TTTTHHHHEEEE    PPPPAAAARRRRAAAAMMMMEEEETTTTEEEERRRRSSSS PPPPAAAASSSSSSSSEEEEDDDD TTTTOOOO YYYYOOOOUUUURRRR
      SSSSCCCCRRRRIIIIPPPPTTTT::::

           @names =    $query->param

      If the script    was invoked with a parameter list (e.g.
      "name1=value1&name2=value2&name3=value3"), the _p_a_r_a_m()
      method will return the parameter names as a list.  If    the
      script was invoked as    an <ISINDEX> script, there will    be a
      single parameter named 'keywords'.

      NOTE:    As of version 1.5, the array of    parameter names
      returned will    be in the same order as    they were submitted by
      the browser.    Usually    this order is the same as the order in
      which    the parameters are defined in the form (however, this
      isn't    part of    the spec, and so isn't guaranteed).



     Page 6                        (printed 10/23/98)






     CCCCGGGGIIII((((3333))))         22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))        CCCCGGGGIIII((((3333))))



      FFFFEEEETTTTCCCCHHHHIIIINNNNGGGG TTTTHHHHEEEE VVVVAAAALLLLUUUUEEEE OOOORRRR    VVVVAAAALLLLUUUUEEEESSSS OOOOFFFF AAAA SSSSIIIINNNNGGGGLLLLEEEE NNNNAAAAMMMMEEEEDDDD PPPPAAAARRRRAAAAMMMMEEEETTTTEEEERRRR::::

          @values =    $query->param('foo');

            -or-

          $value = $query->param('foo');

      Pass the _p_a_r_a_m() method a single argument to fetch the value
      of the named parameter. If the parameter is multivalued
      (e.g.    from multiple selections in a scrolling    list), you can
      ask to receive an array.  Otherwise the method will return a
      single value.

      SSSSEEEETTTTTTTTIIIINNNNGGGG TTTTHHHHEEEE _V_A_L_U_E(S) OF A NAMED PARAMETER:

          $query->param('foo','an','array','of','values');

      This sets the    value for the named parameter 'foo' to an
      array    of values.  This is one    way to change the value    of a
      field    AFTER the script has been invoked once before.
      (Another way is with the -override parameter accepted    by all
      methods that generate    form elements.)

      _p_a_r_a_m() also recognizes a named parameter style of calling
      described in more detail later:

          $query->param(-name=>'foo',-values=>['an','array','of','values']);

                    -or-

          $query->param(-name=>'foo',-value=>'the value');


      AAAAPPPPPPPPEEEENNNNDDDDIIIINNNNGGGG AAAADDDDDDDDIIIITTTTIIIIOOOONNNNAAAALLLL VVVVAAAALLLLUUUUEEEESSSS TTTTOOOO AAAA NNNNAAAAMMMMEEEEDDDD PPPPAAAARRRRAAAAMMMMEEEETTTTEEEERRRR::::

         $query->append(-name=>'foo',-values=>['yet','more','values']);

      This adds a value or list of values to the named parameter.
      The values are appended to the end of    the parameter if it
      already exists.  Otherwise the parameter is created.    Note
      that this method only    recognizes the named argument calling
      syntax.

      IIIIMMMMPPPPOOOORRRRTTTTIIIINNNNGGGG AAAALLLLLLLL    PPPPAAAARRRRAAAAMMMMEEEETTTTEEEERRRRSSSS IIIINNNNTTTTOOOO    AAAA NNNNAAAAMMMMEEEESSSSPPPPAAAACCCCEEEE::::

         $query->import_names('R');

      This creates a series    of variables in    the 'R'    namespace.
      For example, $R::foo,    @R:foo.     For keyword lists, a variable
      @R::keywords will appear.  If    no namespace is    given, this
      method will assume 'Q'.  WARNING:  don't import anything



     Page 7                        (printed 10/23/98)






     CCCCGGGGIIII((((3333))))         22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))        CCCCGGGGIIII((((3333))))



      into risk!!!!

      In older versions, this method was called iiiimmmmppppoooorrrrtttt(((()))).  As of
      version 2.20,    this name has been removed completely to avoid
      conflict with    the built-in Perl module iiiimmmmppppoooorrrrtttt    operator.

      DDDDEEEELLLLEEEETTTTIIIINNNNGGGG AAAA PPPPAAAARRRRAAAAMMMMEEEETTTTEEEERRRR CCCCOOOOMMMMPPPPLLLLEEEETTTTEEEELLLLYYYY::::

          $query->delete('foo');

      This completely clears a parameter.  It sometimes useful for
      resetting parameters that you    don't want passed down between
      script invocations.

      If you are using the function    call interface,    use "_D_e_l_e_t_e()"
      instead to avoid conflicts with Perl's built-in delete
      operator.

      DDDDEEEELLLLEEEETTTTIIIINNNNGGGG AAAALLLLLLLL PPPPAAAARRRRAAAAMMMMEEEETTTTEEEERRRRSSSS::::

         $query->delete_all();

      This clears the CGI object completely.  It might be useful
      to ensure that all the defaults are taken when you create a
      fill-out form.

      Use _D_e_l_e_t_e__a_l_l() instead if you are using the    function call
      interface.

      DDDDIIIIRRRREEEECCCCTTTT AAAACCCCCCCCEEEESSSSSSSS    TTTTOOOO TTTTHHHHEEEE PPPPAAAARRRRAAAAMMMMEEEETTTTEEEERRRR LLLLIIIISSSSTTTT::::

         $q->param_fetch('address')->[1] = '1313 Mockingbird Lane';
         unshift @{$q->param_fetch(-name=>'address')},'George Munster';

      If you need access to    the parameter list in a    way that isn't
      covered by the methods above,    you can    obtain a direct
      reference to it by calling the ppppaaaarrrraaaammmm____ffffeeeettttcccchhhh(((()))) method with the
      name of the .     This will return an array reference to    the
      named    parameters, which you then can manipulate in any way
      you like.

      You can also use a named argument style using    the ----nnnnaaaammmmeeee
      argument.

      SSSSAAAAVVVVIIIINNNNGGGG TTTTHHHHEEEE SSSSTTTTAAAATTTTEEEE OOOOFFFF TTTTHHHHEEEE SSSSCCCCRRRRIIIIPPPPTTTT TTTTOOOO AAAA FFFFIIIILLLLEEEE::::

          $query->save(FILEHANDLE)

      This will write the current state of the form    to the
      provided filehandle.    You can    read it    back in    by providing a
      filehandle to    the _n_e_w() method.  Note    that the filehandle
      can be a file, a pipe, or whatever!



     Page 8                        (printed 10/23/98)






     CCCCGGGGIIII((((3333))))         22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))        CCCCGGGGIIII((((3333))))



      The format of    the saved file is:

          NAME1=VALUE1
          NAME1=VALUE1'
          NAME2=VALUE2
          NAME3=VALUE3
          =

      Both name and    value are URL escaped.    Multi-valued CGI
      parameters are represented as    repeated names.     A session
      record is delimited by a single = symbol.  You can write out
      multiple records and read them back in with several calls to
      nnnneeeewwww.    You can    do this    across several sessions    by opening the
      file in append mode, allowing    you to create primitive    guest
      books, or to keep a history of users'    queries.  Here's a
      short    example    of creating multiple session records:

         use CGI;

         open (OUT,">>test.out") ||    die;
         $records =    5;
         foreach (0..$records) {
         my $q = new CGI;
         $q->param(-name=>'counter',-value=>$_);
         $q->save(OUT);
         }
         close OUT;

         # reopen for reading
         open (IN,"test.out") || die;
         while (!eof(IN)) {
         my $q = new CGI(IN);
         print $q->param('counter'),"\n";
         }

      The file format used for save/restore    is identical to    that
      used by the Whitehead    Genome Center's    data exchange format
      "Boulderio", and can be manipulated and even databased using
      Boulderio utilities.    See
        http://www.genome.wi.mit.edu/genome_software/other/boulder.html

      for further details.

      If you wish to use this method from the function-oriented
      (non-OO) interface, the exported name    for this method    is
      ssssaaaavvvveeee____ppppaaaarrrraaaammmmeeeetttteeeerrrrssss(((()))).

      UUUUSSSSIIIINNNNGGGG    TTTTHHHHEEEE FFFFUUUUNNNNCCCCTTTTIIIIOOOONNNN----OOOORRRRIIIIEEEENNNNTTTTEEEEDDDD IIIINNNNTTTTEEEERRRRFFFFAAAACCCCEEEE

      To use the function-oriented interface, you must specify
      which    CGI.pm routines    or sets    of routines to import into
      your script's    namespace.  There is a small overhead



     Page 9                        (printed 10/23/98)






     CCCCGGGGIIII((((3333))))         22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))        CCCCGGGGIIII((((3333))))



      associated with this importation, but    it isn't much.

         use CGI <list of methods>;

      The listed methods will be imported into the current
      package; you can call    them directly without creating a CGI
      object first.     This example shows how    to import the ppppaaaarrrraaaammmm(((())))
      and hhhheeeeaaaaddddeeeerrrr(((()))) methods,    and then use them directly:

         use CGI 'param','header';
         print header('text/plain');
         $zipcode =    param('zipcode');

      More frequently, you'll import common    sets of    functions by
      referring to the gropus by name.  All    function sets are
      preceded with    a ":"  character as in ":html3"    (for tags
      defined in the HTML 3    standard).

      Here is a list of the    function sets you can import:

      ::::ccccggggiiii
          Import all CGI-handling methods, such as ppppaaaarrrraaaammmm(((()))),
          ppppaaaatttthhhh____iiiinnnnffffoooo(((()))) and the like.

      ::::ffffoooorrrrmmmm
          Import all fill-out form generating methods, such    as
          tttteeeexxxxttttffffiiiieeeelllldddd(((()))).

      ::::hhhhttttmmmmllll2222
          Import all methods that generate HTML 2.0    standard
          elements.

      ::::hhhhttttmmmmllll3333
          Import all methods that generate HTML 3.0    proposed
          elements (such as    <table>, <super> and <sub>).

      ::::nnnneeeettttssssccccaaaappppeeee
          Import all methods that generate Netscape-specific HTML
          extensions.

      ::::hhhhttttmmmmllll
          Import all HTML-generating shortcuts (i.e. 'html2' +
          'html3' +    'netscape')...

      ::::ssssttttaaaannnnddddaaaarrrrdddd
          Import "standard"    features, 'html2', 'html3', 'form' and
          'cgi'.

      ::::aaaallllllll
          Import all the available methods.     For the full list,
          see the CGI.pm code, where the variable %TAGS is
          defined.



     Page 10                        (printed 10/23/98)






     CCCCGGGGIIII((((3333))))         22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))        CCCCGGGGIIII((((3333))))



      If you import    a function name    that is    not part of CGI.pm,
      the module will treat    it as a    new HTML tag and generate the
      appropriate subroutine.  You can then    use it like any    other
      HTML tag.  This is to    provide    for the    rapidly-evolving HTML
      "standard."  For example, say    Microsoft comes    out with a new
      tag called <GRADIENT>    (which causes the user's desktop to be
      flooded with a rotating gradient fill    until his machine
      reboots).  You don't need to wait for    a new version of
      CGI.pm to start using    it immeidately:

         use CGI qw/:standard :html3 gradient/;
         print gradient({-start=>'red',-end=>'blue'});

      Note that in the interests of    execution speed    CGI.pm does
      nnnnooootttt use the standard the _E_x_p_o_r_t_e_r manpage syntax for
      specifying load symbols.  This may change in the future.

      If you import    any of the state-maintaining CGI or form-
      generating methods, a    default    CGI object will    be created and
      initialized automatically the    first time you use any of the
      methods that require one to be present.  This    includes
      ppppaaaarrrraaaammmm(((()))), tttteeeexxxxttttffffiiiieeeelllldddd(((()))),    ssssuuuubbbbmmmmiiiitttt(((()))) and the like.    (If you    need
      direct access    to the CGI object, you can find    it in the
      global variable $$$$CCCCGGGGIIII::::::::QQQQ).  By    importing CGI.pm methods, you
      can create visually elegant scripts:

         use CGI qw/:standard/;
         print
         header,
         start_html('Simple Script'),
         h1('Simple Script'),
         start_form,
         "What's your name? ",textfield('name'),p,
         "What's the combination?",
         checkbox_group(-name=>'words',
                -values=>['eenie','meenie','minie','moe'],
                -defaults=>['eenie','moe']),p,
         "What's your favorite color?",
         popup_menu(-name=>'color',
                -values=>['red','green','blue','chartreuse']),p,
         submit,
         end_form,
         hr,"\n";

          if (param) {
         print
             "Your name    is ",em(param('name')),p,
             "The keywords are:    ",em(join(", ",param('words'))),p,
             "Your favorite color is ",em(param('color')),".\n";
          }
          print end_html;




     Page 11                        (printed 10/23/98)






     CCCCGGGGIIII((((3333))))         22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))        CCCCGGGGIIII((((3333))))



      PPPPRRRRAAAAGGGGMMMMAAAASSSS

      In addition to the function sets, there are a    number of
      pragmas that you can import.    Pragmas, which are always
      preceded by a    hyphen,    change the way that CGI.pm functions
      in various ways.  Pragmas, function sets, and    individual
      functions can    all be imported    in the same _u_s_e() line.     For
      example, the following use statement imports the standard
      set of functions and disables    debugging mode (pragma
      -no_debug):

         use CGI qw/:standard -no_debug/;

      The current list of pragmas is as follows:

      -any
          When you _u_s_e _C_G_I -_a_n_y, then any method that the query
          object doesn't recognize will be interpreted as a    new
          HTML tag.     This allows you to support the    next _a_d    _h_o_c
          Netscape or Microsoft HTML extension.  This lets you go
          wild with    new and    unsupported tags:

         use CGI qw(-any);
         $q=new    CGI;
         print $q->gradient({speed=>'fast',start=>'red',end=>'blue'});

          Since using <cite>any</cite> causes any mistyped method
          name to be interpreted as    an HTML    tag, use it with care
          or not at    all.

      -compile
          This causes the indicated    autoloaded methods to be
          compiled up front, rather    than deferred to later.     This
          is useful    for scripts that run for an extended period of
          time under FastCGI or mod_perl, and for those destined
          to be crunched by    Malcom Beattie's Perl compiler.     Use
          it in conjunction    with the methods or method familes you
          plan to use.

         use CGI qw(-compile :standard :html3);

          or even

         use CGI qw(-compile :all);

          Note that    using the -compile pragma in this way will
          always have the effect of    importing the compiled
          functions    into the current namespace.  If    you want to
          compile without importing    use the    _c_o_m_p_i_l_e() method
          instead (see below).





     Page 12                        (printed 10/23/98)






     CCCCGGGGIIII((((3333))))         22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))        CCCCGGGGIIII((((3333))))



      -nph
          This makes CGI.pm    produce    a header appropriate for an
          NPH (no parsed header) script.  You may need to do other
          things as    well to    tell the server    that the script    is
          NPH.  See    the discussion of NPH scripts below.

      -autoload
          This overrides the autoloader so that any    function in
          your program that    is not recognized is referred to
          CGI.pm for possible evaluation.  This allows you to use
          all the CGI.pm functions without adding them to your
          symbol table, which is of    concern    for mod_perl users who
          are worried about    memory consumption.  _W_a_r_n_i_n_g: when
          -_a_u_t_o_l_o_a_d    is in effect, you cannot use "poetry mode"
          (functions without the parenthesis).  Use    _h_r() rather
          than _h_r, or add something    like _u_s_e _s_u_b_s _q_w/_h_r _p _h_e_a_d_e_r/
          to the top of your script.

      -no_debug
          This turns off the command-line processing features.  If
          you want to run a    CGI.pm script from the command line to
          produce HTML, and    you don't want it pausing to request
          CGI parameters from standard input or the    command    line,
          then use this pragma:

         use CGI qw(-no_debug :standard);

          If you'd like to process the command-line    parameters but
          not standard input, this should work:

         use CGI qw(-no_debug :standard);
         restore_parameters(join('&',@ARGV));

          See the section on debugging for more details.


      -private_tempfiles
          CGI.pm can process uploaded file.    Ordinarily it spools
          the uploaded file    to a temporary directory, then deletes
          the file when done.  However, this opens the risk    of
          eavesdropping as described in the    file upload section.
          Another CGI script author    could peek at this data    during
          the upload, even if it is    confidential information. On
          Unix systems, the    -private_tempfiles pragma will cause
          the temporary file to be unlinked    as soon    as it is
          opened and before    any data is written into it,
          eliminating the risk of eavesdropping.  n    =back

     GGGGEEEENNNNEEEERRRRAAAATTTTIIIINNNNGGGG    DDDDYYYYNNNNAAAAMMMMIIIICCCC    DDDDOOOOCCCCUUUUMMMMEEEENNNNTTTTSSSS
      Most of CGI.pm's functions deal with creating    documents on
      the fly.  Generally you will produce the HTTP    header first,
      followed by the document itself.  CGI.pm provides functions



     Page 13                        (printed 10/23/98)






     CCCCGGGGIIII((((3333))))         22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))        CCCCGGGGIIII((((3333))))



      for generating HTTP headers of various types as well as for
      generating HTML.  For    creating GIF images, see the GD.pm
      module.

      Each of these    functions produces a fragment of HTML or HTTP
      which    you can    print out directly so that it displays in the
      browser window, append to a string, or save to a file    for
      later    use.

      CCCCRRRREEEEAAAATTTTIIIINNNNGGGG AAAA SSSSTTTTAAAANNNNDDDDAAAARRRRDDDD HHHHTTTTTTTTPPPP HHHHEEEEAAAADDDDEEEERRRR::::

      Normally the first thing you will do in any CGI script is
      print    out an HTTP header.  This tells    the browser what type
      of document to expect, and gives other optional information,
      such as the language,    expiration date, and whether to    cache
      the document.     The header can    also be    manipulated for
      special purposes, such as server push    and pay    per view
      pages.

          print    $query->header;

               -or-

          print    $query->header('image/gif');

               -or-

          print    $query->header('text/html','204    No response');

               -or-

          print    $query->header(-type=>'image/gif',
                       -nph=>1,
                       -status=>'402 Payment required',
                       -expires=>'+3d',
                       -cookie=>$cookie,
                       -Cost=>'$2.00');

      _h_e_a_d_e_r() returns the Content-type: header.  You can provide
      your own MIME    type if    you choose, otherwise it defaults to
      text/html.  An optional second parameter specifies the
      status code and a human-readable message.  For example, you
      can specify 204, "No response" to create a script that tells
      the browser to do nothing at all.

      The last example shows the named argument style for passing
      arguments to the CGI methods using named parameters.
      Recognized parameters    are ----ttttyyyyppppeeee, ----ssssttttaaaattttuuuussss, ----eeeexxxxppppiiiirrrreeeessss, and
      ----ccccooooooookkkkiiiieeee.  Any    other named parameters will be stripped    of
      their    initial    hyphens    and turned into    header fields,
      allowing you to specify any HTTP header you desire.
      Internal underscores will be turned into hyphens:



     Page 14                        (printed 10/23/98)






     CCCCGGGGIIII((((3333))))         22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))        CCCCGGGGIIII((((3333))))



          print $query->header(-Content_length=>3002);

      Most browsers    will not cache the output from CGI scripts.
      Every    time the browser reloads the page, the script is
      invoked anew.     You can change    this behavior with the
      ----eeeexxxxppppiiiirrrreeeessss parameter.  When you    specify    an absolute or
      relative expiration interval with this parameter, some
      browsers and proxy servers will cache    the script's output
      until    the indicated expiration date.    The following forms
      are all valid    for the    -expires field:

          +30s                    30 seconds from now
          +10m                    ten    minutes    from now
          +1h                    one    hour from now
          -1d                    yesterday (i.e. "ASAP!")
          now                    immediately
          +3M                    in three months
          +10y                    in ten years time
          Thursday, 25-Apr-1999    00:40:33 GMT  at the indicated time & date

      The ----ccccooooooookkkkiiiieeee parameter    generates a header that    tells the
      browser to provide a "magic cookie" during all subsequent
      transactions with your script.  Netscape cookies have    a
      special format that includes interesting attributes such as
      expiration time.  Use    the _c_o_o_k_i_e() method to create and
      retrieve session cookies.

      The ----nnnnpppphhhh parameter, if set to    a true value, will issue the
      correct headers to work with a NPH (no-parse-header) script.
      This is important to use with    certain    servers, such as
      Microsoft Internet Explorer, which expect all    their scripts
      to be    NPH.

      GGGGEEEENNNNEEEERRRRAAAATTTTIIIINNNNGGGG AAAA RRRREEEEDDDDIIIIRRRREEEECCCCTTTTIIIIOOOONNNN HHHHEEEEAAAADDDDEEEERRRR

         print $query->redirect('http://somewhere.else/in/movie/land');

      Sometimes you    don't want to produce a    document yourself, but
      simply redirect the browser elsewhere, perhaps choosing a
      URL based on the time    of day or the identity of the user.

      The _r_e_d_i_r_e_c_t() function redirects the    browser    to a different
      URL.    If you use redirection like this, you should nnnnooootttt print
      out a    header as well.     As of version 2.0, we produce both
      the unofficial Location:  header and the official URI:
      header.  This    should satisfy most servers and    browsers.

      One hint I can offer is that relative    links may not work
      correctly when you generate a    redirection to another
      document on your site.  This is due to a well-intentioned
      optimization that some servers use.  The solution to this is
      to use the full URL (including the http: part) of the



     Page 15                        (printed 10/23/98)






     CCCCGGGGIIII((((3333))))         22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))        CCCCGGGGIIII((((3333))))



      document you are redirecting to.

      You can also use named arguments:

          print $query->redirect(-uri=>'http://somewhere.else/in/movie/land',
                     -nph=>1);

      The ----nnnnpppphhhh parameter, if set to    a true value, will issue the
      correct headers to work with a NPH (no-parse-header) script.
      This is important to use with    certain    servers, such as
      Microsoft Internet Explorer, which expect all    their scripts
      to be    NPH.

      CCCCRRRREEEEAAAATTTTIIIINNNNGGGG TTTTHHHHEEEE HHHHTTTTMMMMLLLL DDDDOOOOCCCCUUUUMMMMEEEENNNNTTTT HHHHEEEEAAAADDDDEEEERRRR

         print $query->start_html(-title=>'Secrets of the Pyramids',
                      -author=>'[e-mail]',
                      -base=>'true',
                      -target=>'_blank',
                      -meta=>{'keywords'=>'pharaoh secret mummy',
                          'copyright'=>'copyright 1996 King    Tut'},
                      -style=>{'src'=>'/styles/style1.css'},
                      -BGCOLOR=>'blue');

      After    creating the HTTP header, most CGI scripts will    start
      writing out an HTML document.     The _s_t_a_r_t__h_t_m_l() routine
      creates the top of the page, along with a lot    of optional
      information that controls the    page's appearance and
      behavior.

      This method returns a    canned HTML header and the opening
      <BODY> tag.  All parameters are optional.  In    the named
      parameter form, recognized parameters    are -title, -author,
      -base, -xbase    and -target (see below for the explanation).
      Any additional parameters you    provide, such as the Netscape
      unofficial BGCOLOR attribute,    are added to the <BODY>    tag.
      Additional parameters    must be    proceeded by a hyphen.

      The argument ----xxxxbbbbaaaasssseeee allows you to provide an HREF for    the
      <BASE> tag different from the    current    location, as in

          -xbase=>"http://home.mcom.com/"

      All relative links will be interpreted relative to this tag.

      The argument ----ttttaaaarrrrggggeeeetttt allows you to provide a default target
      frame    for all    the links and fill-out forms on    the page.  See
      the Netscape documentation on    frames for details of how to
      manipulate this.

          -target=>"answer_window"




     Page 16                        (printed 10/23/98)






     CCCCGGGGIIII((((3333))))         22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))        CCCCGGGGIIII((((3333))))



      All relative links will be interpreted relative to this tag.
      You add arbitrary meta information to    the header with    the
      ----mmmmeeeettttaaaa    argument.  This    argument expects a reference to    an
      associative array containing name/value pairs    of meta
      information.    These will be turned into a series of header
      <META> tags that look    something like this:

          <META NAME="keywords" CONTENT="pharaoh secret mummy">
          <META NAME="description" CONTENT="copyright 1996 King Tut">

      There    is no support for the HTTP-EQUIV type of <META>    tag.
      This is because you can modify the HTTP header directly with
      the hhhheeeeaaaaddddeeeerrrr(((()))) method.    For example, if    you want to send the
      Refresh: header, do it in the    _h_e_a_d_e_r() method:

          print $q->header(-Refresh=>'10; URL=http://www.capricorn.com');

      The ----ssssttttyyyylllleeee tag is used to incorporate    cascading stylesheets
      into your code.  See the section on CASCADING    STYLESHEETS
      for more information.

      You can place    other arbitrary    HTML elements to the <HEAD>
      section with the ----hhhheeeeaaaadddd tag.  For example, to place the
      rarely-used <LINK> element in    the head section, use this:

          print $q->start_html(-head=>Link({-rel=>'next',
                        -href=>'http://www.capricorn.com/s2.html'}));

      To incorporate multiple HTML elements    into the <HEAD>
      section, just    pass an    array reference:

          print $q->start_html(-head=>[
                    Link({-rel=>'next',
                          -href=>'http://www.capricorn.com/s2.html'}),
                    Link({-rel=>'previous',
                          -href=>'http://www.capricorn.com/s1.html'})
                       ]
                   );

      JAVASCRIPTING: The ----ssssccccrrrriiiipppptttt, ----nnnnooooSSSSccccrrrriiiipppptttt, ----oooonnnnLLLLooooaaaadddd,
      ----oooonnnnMMMMoooouuuusssseeeeOOOOvvvveeeerrrr,    ----oooonnnnMMMMoooouuuusssseeeeOOOOuuuutttt and    ----oooonnnnUUUUnnnnllllooooaaaadddd parameters are used
      to add Netscape JavaScript calls to your pages.  ----ssssccccrrrriiiipppptttt
      should point to a block of text containing JavaScript
      function definitions.     This block will be placed within a
      <SCRIPT> block inside    the HTML (not HTTP) header.  The block
      is placed in the header in order to give your    page a
      fighting chance of having all    its JavaScript functions in
      place    even if    the user presses the stop button before    the
      page has loaded completely.  CGI.pm attempts to format the
      script in such a way that JavaScript-naive browsers will not
      choke    on the code: unfortunately there are some browsers,
      such as Chimera for Unix, that get confused by it



     Page 17                        (printed 10/23/98)






     CCCCGGGGIIII((((3333))))         22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))        CCCCGGGGIIII((((3333))))



      nevertheless.

      The ----oooonnnnLLLLooooaaaadddd and ----oooonnnnUUUUnnnnllllooooaaaadddd parameters point to    fragments of
      JavaScript code to execute when the page is respectively
      opened and closed by the browser.  Usually these parameters
      are calls to functions defined in the    ----ssssccccrrrriiiipppptttt    field:

        $query = new CGI;
        print $query->header;
        $JSCRIPT=<<END;
        // Ask a silly question
        function riddle_me_this() {
           var r = prompt("What    walks on four legs in the morning, " +
                 "two legs in the afternoon, " +
                 "and three legs in the    evening?");
           response(r);
        }
        // Get a silly answer
        function response(answer) {
           if (answer == "man")
              alert("Right you are!");
           else
              alert("Wrong!  Guess again.");
        }
        END
        print $query->start_html(-title=>'The Riddle of    the Sphinx',
                     -script=>$JSCRIPT);

      Use the ----nnnnooooSSSSccccrrrriiiipppptttt parameter to pass some HTML    text that will
      be displayed on browsers that    do not have JavaScript (or
      browsers where JavaScript is turned off).

      Netscape 3.0 recognizes several attributes of    the <SCRIPT>
      tag, including LANGUAGE and SRC.  The    latter is particularly
      interesting, as it allows you    to keep    the JavaScript code in
      a file or CGI    script rather than cluttering up each page
      with the source.  To use these attributes pass a HASH
      reference in the ----ssssccccrrrriiiipppptttt parameter containing    one or more of
      -language, -src, or -code:

          print $q->start_html(-title=>'The    Riddle of the Sphinx',
                   -script=>{-language=>'JAVASCRIPT',
                         -src=>'/javascript/sphinx.js'}
                   );

          print $q->(-title=>'The Riddle of    the Sphinx',
             -script=>{-language=>'PERLSCRIPT'},
                   -code=>'print "hello    world!\n;"'
             );

      A final feature allows you to    incorporate multiple <SCRIPT>
      sections into    the header.  Just pass the list    of script



     Page 18                        (printed 10/23/98)






     CCCCGGGGIIII((((3333))))         22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))        CCCCGGGGIIII((((3333))))



      sections as an array reference.  this    allows you to specify
      different source files for different dialects    of JavaScript.
      Example:

           print $q->start_html(-title=>'The Riddle of the Sphinx',
                    -script=>[
                          {    -language =>    'JavaScript1.0',
                        -src      =>    '/javascript/utilities10.js'
                          },
                          {    -language =>    'JavaScript1.1',
                        -src      =>    '/javascript/utilities11.js'
                          },
                          {    -language =>    'JavaScript1.2',
                        -src      =>    '/javascript/utilities12.js'
                          },
                          {    -language =>    'JavaScript28.2',
                        -src      =>    '/javascript/utilities219.js'
                          }
                       ]
                       );
           </pre>

      If this looks    a bit extreme, take my advice and stick    with
      straight CGI scripting.

      See

         http://home.netscape.com/eng/mozilla/2.0/handbook/javascript/

      for more information about JavaScript.

      The old-style    positional parameters are as follows:

      PPPPaaaarrrraaaammmmeeeetttteeeerrrrssss::::

      1.      The title

      2.      The author's e-mail address (will create a <LINK
          REV="MADE"> tag if present

      3.      A 'true' flag    if you want to include a <BASE>    tag in
          the header.  This helps resolve relative addresses
          to absolute ones when    the document is    moved, but
          makes    the document hierarchy non-portable.  Use with
          care!

      4, 5,    6...
          Any other parameters you want    to include in the
          <BODY> tag.  This is a good place to put Netscape
          extensions, such as colors and wallpaper patterns.





     Page 19                        (printed 10/23/98)






     CCCCGGGGIIII((((3333))))         22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))        CCCCGGGGIIII((((3333))))



      EEEENNNNDDDDIIIINNNNGGGG TTTTHHHHEEEE HHHHTTTTMMMMLLLL DDDDOOOOCCCCUUUUMMMMEEEENNNNTTTT::::

          print    $query->end_html

      This ends an HTML document by    printing the </BODY></HTML>
      tags.

      CCCCRRRREEEEAAAATTTTIIIINNNNGGGG AAAA SSSSEEEELLLLFFFF----RRRREEEEFFFFEEEERRRREEEENNNNCCCCIIIINNNNGGGG UUUURRRRLLLL TTTTHHHHAAAATTTT PPPPRRRREEEESSSSEEEERRRRVVVVEEEESSSS SSSSTTTTAAAATTTTEEEE
      IIIINNNNFFFFOOOORRRRMMMMAAAATTTTIIIIOOOONNNN::::

          $myself =    $query->self_url;
          print "<A    HREF=$myself>I'm talking to myself.</A>";

      _s_e_l_f__u_r_l() will return a URL,    that, when selected, will
      reinvoke this    script with all    its state information intact.
      This is most useful when you want to jump around within the
      document using internal anchors but you don't    want to
      disrupt the current contents of the _f_o_r_m(s).    Something like
      this will do the trick.

           $myself = $query->self_url;
           print "<A HREF=$myself#table1>See table 1</A>";
           print "<A HREF=$myself#table2>See table 2</A>";
           print "<A HREF=$myself#yourself>See for yourself</A>";

      If you want more control over    what's returned, using the
      uuuurrrrllll(((())))    method instead.

      You can also retrieve    the unprocessed    query string with
      _q_u_e_r_y__s_t_r_i_n_g():

          $the_string = $query->query_string;


      OOOOBBBBTTTTAAAAIIIINNNNIIIINNNNGGGG TTTTHHHHEEEE    SSSSCCCCRRRRIIIIPPPPTTTT''''SSSS UUUURRRRLLLL

          $full_url         = $query->url();
          $full_url         = $query->url(-full=>1);  #alternative syntax
          $relative_url  = $query->url(-relative=>1);
          $absolute_url  = $query->url(-absolute=>1);
          $url_with_path = $query->url(-path_info=>1);
          $url_with_path_and_query = $query->url(-path_info=>1,-query=>1);

      uuuurrrrllll(((())))    returns    the script's URL in a variety of formats.
      Called without any arguments,    it returns the full form of
      the URL, including host name and port    number

          http://your.host.com/path/to/script.cgi

      You can modify this format with the following    named
      arguments:




     Page 20                        (printed 10/23/98)






     CCCCGGGGIIII((((3333))))         22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))        CCCCGGGGIIII((((3333))))



      ----aaaabbbbssssoooolllluuuutttteeee
          If true, produce an absolute URL, e.g.

              /path/to/script.cgi


      ----rrrreeeellllaaaattttiiiivvvveeee
          Produce a relative URL.  This    is useful if you want
          to reinvoke your script with different parameters.
          For example:

              script.cgi


      ----ffffuuuullllllll      Produce the full URL,    exactly    as if called without
          any arguments.  This overrides the -relative and
          -absolute arguments.

      ----ppppaaaatttthhhh    (----ppppaaaatttthhhh____iiiinnnnffffoooo)
          Append the additional    path information to the    URL.
          This can be combined with ----ffffuuuullllllll, ----aaaabbbbssssoooolllluuuutttteeee or
          ----rrrreeeellllaaaattttiiiivvvveeee.  ----ppppaaaatttthhhh____iiiinnnnffffoooo is provided as    a synonym.

      ----qqqquuuueeeerrrryyyy (----qqqquuuueeeerrrryyyy____ssssttttrrrriiiinnnngggg)
          Append the query string to the URL.  This can    be
          combined with    ----ffffuuuullllllll, ----aaaabbbbssssoooolllluuuutttteeee or ----rrrreeeellllaaaattttiiiivvvveeee.
          ----qqqquuuueeeerrrryyyy____ssssttttrrrriiiinnnngggg    is provided as a synonym.

     CCCCRRRREEEEAAAATTTTIIIINNNNGGGG SSSSTTTTAAAANNNNDDDDAAAARRRRDDDD HHHHTTTTMMMMLLLL EEEELLLLEEEEMMMMEEEENNNNTTTTSSSS::::
      CGI.pm defines general HTML shortcut methods for most, if
      not all of the HTML 3    and HTML 4 tags.  HTML shortcuts are
      named    after a    single HTML element and    return a fragment of
      HTML text that you can then print or manipulate as you like.
      Each shortcut    returns    a fragment of HTML code    that you can
      append to a string, save to a    file, or, most commonly, print
      out so that it displays in the browser window.

      This example shows how to use    the HTML methods:

         $q    = new CGI;
         print $q->blockquote(
                   "Many years ago on the island of",
                   $q->a({href=>"http://crete.org/"},"Crete"),
                   "there lived a minotaur named",
                   $q->strong("Fred."),
                  ),
         $q->hr;

      This results in the following    HTML code (extra newlines have
      been added for readability):





     Page 21                        (printed 10/23/98)






     CCCCGGGGIIII((((3333))))         22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))        CCCCGGGGIIII((((3333))))



         <blockquote>
         Many years    ago on the island of
         <a    HREF="http://crete.org/">Crete</a> there lived
         a minotaur    named <strong>Fred.</strong>
         </blockquote>
         <hr>

      If you find the syntax for calling the HTML shortcuts
      awkward, you can import them into your namespace and
      dispense with    the object syntax completely (see the next
      section for more details):

         use CGI ':standard';
         print blockquote(
        "Many years ago    on the island of",
        a({href=>"http://crete.org/"},"Crete"),
        "there lived a minotaur    named",
        strong("Fred."),
        ),
        hr;


      PPPPRRRROOOOVVVVIIIIDDDDIIIINNNNGGGG AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS TTTTOOOO HHHHTTTTMMMMLLLL SSSSHHHHOOOORRRRTTTTCCCCUUUUTTTTSSSS

      The HTML methods will    accept zero, one or multiple
      arguments.  If you provide no    arguments, you get a single
      tag:

         print hr;      #  <HR>

      If you provide one or    more string arguments, they are
      concatenated together    with spaces and    placed between opening
      and closing tags:

         print h1("Chapter","1"); #    <H1>Chapter 1</H1>"

      If the first argument    is an associative array    reference,
      then the keys    and values of the associative array become the
      HTML tag's attributes:

         print a({-href=>'fred.html',-target=>'_new'},
        "Open a    new frame");

              <A HREF="fred.html",TARGET="_new">Open a new frame</A>

      You may dispense with    the dashes in front of the attribute names if
      you prefer:

         print img {src=>'fred.gif',align=>'LEFT'};

             <IMG ALIGN="LEFT" SRC="fred.gif">




     Page 22                        (printed 10/23/98)






     CCCCGGGGIIII((((3333))))         22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))        CCCCGGGGIIII((((3333))))



      Sometimes an HTML tag    attribute has no argument.  For
      example, ordered lists can be    marked as COMPACT.  The    syntax
      for this is an argument that that points to an undef string:

         print ol({compact=>undef},li('one'),li('two'),li('three'));

      Prior    to CGI.pm version 2.41,    providing an empty ('')    string
      as an    attribute argument was the same    as providing undef.
      However, this    has changed in order to    accomodate those who
      want to create tags of the form <IMG ALT="">.     The
      difference is    shown in these two pieces of code:

         CODE            RESULT
         _i_m_g({alt=>undef})        <IMG ALT>
         _i_m_g({alt=>''})        <IMT ALT="">

      TTTTHHHHEEEE DDDDIIIISSSSTTTTRRRRIIIIBBBBUUUUTTTTIIIIVVVVEEEE PPPPRRRROOOOPPPPEEEERRRRTTTTYYYY OOOOFFFF HHHHTTTTMMMMLLLL SSSSHHHHOOOORRRRTTTTCCCCUUUUTTTTSSSS

      One of the cool features of the HTML shortcuts is that they
      are distributive.  If    you give them an argument consisting
      of a rrrreeeeffffeeeerrrreeeennnncccceeee to a list, the    tag will be distributed    across
      each element of the list.  For example, here's one way to
      make an ordered list:

         print ul(
               li({-type=>'disc'},['Sneezy','Doc','Sleepy','Happy']);
             );

      This example will result in HTML output that looks like
      this:

         <UL>
           <LI TYPE="disc">Sneezy</LI>
           <LI TYPE="disc">Doc</LI>
           <LI TYPE="disc">Sleepy</LI>
           <LI TYPE="disc">Happy</LI>
         </UL>

      This is extremely useful for creating    tables.     For example:

         print table({-border=>undef},
             caption('When Should You Eat Your Vegetables?'),
             Tr({-align=>CENTER,-valign=>TOP},
             [
            th(['Vegetable', 'Breakfast','Lunch','Dinner']),
            td(['Tomatoes' , 'no', 'yes', 'yes']),
            td(['Broccoli' , 'no', 'no',  'yes']),
            td(['Onions'   , 'yes','yes', 'yes'])
             ]
             )
          );




     Page 23                        (printed 10/23/98)






     CCCCGGGGIIII((((3333))))         22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))        CCCCGGGGIIII((((3333))))



      HHHHTTTTMMMMLLLL SSSSHHHHOOOORRRRTTTTCCCCUUUUTTTTSSSS AAAANNNNDDDD LLLLIIIISSSSTTTT IIIINNNNTTTTEEEERRRRPPPPOOOOLLLLAAAATTTTIIIIOOOONNNN

      Consider this    bit of code:

         print blockquote(em('Hi'),'mom!'));

      It will ordinarily return the    string that you    probably
      expect, namely:

         <BLOCKQUOTE><EM>Hi</EM> mom!</BLOCKQUOTE>

      Note the space between the element "Hi" and the element
      "mom!".  CGI.pm puts the extra space there using array
      interpolation, which is controlled by    the magic $" variable.
      Sometimes this extra space is    not what you want, for
      example, when    you are    trying to align    a series of images.
      In this case,    you can    simply change the value    of $" to an
      empty    string.

         {
        local($") = '';
        print blockquote(em('Hi'),'mom!'));
          }

      I suggest you    put the    code in    a block    as shown here.
      Otherwise the    change to $" will affect all subsequent    code
      until    you explicitly reset it.

      NNNNOOOONNNN----SSSSTTTTAAAANNNNDDDDAAAARRRRDDDD HHHHTTTTMMMMLLLL SSSSHHHHOOOORRRRTTTTCCCCUUUUTTTTSSSS

      A few    HTML tags don't    follow the standard pattern for
      various reasons.

      ccccoooommmmmmmmeeeennnntttt(((()))) generates an HTML comment (<!-- comment -->).
      Call it like

          print comment('here is my    comment');

      Because of conflicts with built-in Perl functions, the
      following functions begin with initial caps:

          Select
          Tr
          Link
          Delete

      In addition, _s_t_a_r_t__h_t_m_l(), _e_n_d__h_t_m_l(), _s_t_a_r_t__f_o_r_m(),
      _e_n_d__f_o_r_m(), _s_t_a_r_t__m_u_l_t_i_p_a_r_t__f_o_r_m() and all the fill-out form
      tags are special.  See their respective sections.

     CCCCRRRREEEEAAAATTTTIIIINNNNGGGG FFFFIIIILLLLLLLL----OOOOUUUUTTTT FFFFOOOORRRRMMMMSSSS::::
      _G_e_n_e_r_a_l _n_o_t_e    The various form-creating methods all return



     Page 24                        (printed 10/23/98)






     CCCCGGGGIIII((((3333))))         22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))        CCCCGGGGIIII((((3333))))



      strings to the caller, containing the    tag or tags that will
      create the requested form element.  You are responsible for
      actually printing out    these strings.    It's set up this way
      so that you can place    formatting tags    around the form
      elements.

      _A_n_o_t_h_e_r _n_o_t_e The default values that you specify for the
      forms    are only used the ffffiiiirrrrsssstttt    time the script    is invoked
      (when    there is no query string).  On subsequent invocations
      of the script    (when there is a query string),    the former
      values are used even if they are blank.

      If you want to change    the value of a field from its previous
      value, you have two choices:

      (1) call the _p_a_r_a_m() method to set it.

      (2) use the -override    (alias -force) parameter (a new
      feature in version 2.15).  This forces the default value to
      be used, regardless of the previous value:

         print $query->textfield(-name=>'field_name',
                     -default=>'starting value',
                     -override=>1,
                     -size=>50,
                     -maxlength=>80);

      _Y_e_t _a_n_o_t_h_e_r _n_o_t_e By default, the text    and labels of form
      elements are escaped according to HTML rules.     This means
      that you can safely use "<CLICK ME>" as the label for    a
      button.  However, it also interferes with your ability to
      incorporate special HTML character sequences,    such as
      Á, into your fields.  If you wish to turn off
      automatic escaping, call the _a_u_t_o_E_s_c_a_p_e() method with    a
      false    value immediately after    creating the CGI object:

         $query = new CGI;
         $query->autoEscape(undef);



      CCCCRRRREEEEAAAATTTTIIIINNNNGGGG AAAANNNN IIIISSSSIIIINNNNDDDDEEEEXXXX TTTTAAAAGGGG

         print $query->isindex(-action=>$action);

           -or-

         print $query->isindex($action);

      Prints out an    <ISINDEX> tag.    Not very exciting.  The
      parameter -action specifies the URL of the script to process
      the query.  The default is to    process    the query with the



     Page 25                        (printed 10/23/98)






     CCCCGGGGIIII((((3333))))         22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))        CCCCGGGGIIII((((3333))))



      current script.

      SSSSTTTTAAAARRRRTTTTIIIINNNNGGGG AAAANNNNDDDD EEEENNNNDDDDIIIINNNNGGGG AAAA    FFFFOOOORRRRMMMM

          print $query->startform(-method=>$method,
                      -action=>$action,
                      -encoding=>$encoding);
        <... various form stuff    ...>
          print $query->endform;

          -or-

          print $query->startform($method,$action,$encoding);
        <... various form stuff    ...>
          print $query->endform;

      _s_t_a_r_t_f_o_r_m() will return a <FORM> tag with the    optional
      method, action and form encoding that    you specify.  The
      defaults are:
          method: POST
          action: this script
          encoding:    application/x-www-form-urlencoded

      _e_n_d_f_o_r_m() returns the    closing    </FORM>    tag.

      _S_t_a_r_t_f_o_r_m()'s    encoding method    tells the browser how to
      package the various fields of    the form before    sending    the
      form to the server.  Two values are possible:

      aaaapppppppplllliiiiccccaaaattttiiiioooonnnn////xxxx----wwwwwwwwwwww----ffffoooorrrrmmmm----uuuurrrrlllleeeennnnccccooooddddeeeedddd
          This is the older type of encoding used by all
          browsers prior to Netscape 2.0.  It is compatible
          with many CGI    scripts    and is suitable    for short
          fields containing text data.    For your convenience,
          CGI.pm stores    the name of this encoding type in
          $$$$CCCCGGGGIIII::::::::UUUURRRRLLLL____EEEENNNNCCCCOOOODDDDEEEEDDDD.

      mmmmuuuullllttttiiiippppaaaarrrrtttt////ffffoooorrrrmmmm----ddddaaaattttaaaa
          This is the newer type of encoding introduced    by
          Netscape 2.0.     It is suitable    for forms that contain
          very large fields or that are    intended for
          transferring binary data.  Most importantly, it
          enables the "file upload" feature of Netscape    2.0
          forms.  For your convenience,    CGI.pm stores the name
          of this encoding type    in &&&&CCCCGGGGIIII::::::::MMMMUUUULLLLTTTTIIIIPPPPAAAARRRRTTTT

          Forms    that use this type of encoding are not easily
          interpreted by CGI scripts unless they use CGI.pm or
          another library designed to handle them.

          For compatibility, the _s_t_a_r_t_f_o_r_m() method uses the
          older    form of    encoding by default.  If you want to



     Page 26                        (printed 10/23/98)






     CCCCGGGGIIII((((3333))))         22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))        CCCCGGGGIIII((((3333))))



          use the newer    form of    encoding by default, you can
          call ssssttttaaaarrrrtttt____mmmmuuuullllttttiiiippppaaaarrrrtttt____ffffoooorrrrmmmm(((()))) instead of ssssttttaaaarrrrttttffffoooorrrrmmmm(((()))).

          JAVASCRIPTING: The ----nnnnaaaammmmeeee and ----oooonnnnSSSSuuuubbbbmmmmiiiitttt parameters
          are provided for use with JavaScript.     The -name
          parameter gives the form a name so that it can be
          identified and manipulated by    JavaScript functions.
          -onSubmit should point to a JavaScript function that
          will be executed just    before the form    is submitted
          to your server.  You can use this opportunity    to
          check    the contents of    the form for consistency and
          completeness.     If you    find something wrong, you can
          put up an alert box or maybe fix things up yourself.
          You can abort    the submission by returning false from
          this function.

          Usually the bulk of JavaScript functions are defined
          in a <SCRIPT>    block in the HTML header and -onSubmit
          points to one    of these function call.     See
          _s_t_a_r_t__h_t_m_l() for details.

      CCCCRRRREEEEAAAATTTTIIIINNNNGGGG AAAA TTTTEEEEXXXXTTTT FFFFIIIIEEEELLLLDDDD

          print $query->textfield(-name=>'field_name',
                      -default=>'starting value',
                      -size=>50,
                      -maxlength=>80);
          -or-

          print $query->textfield('field_name','starting value',50,80);

      _t_e_x_t_f_i_e_l_d() will return a text input field.

      PPPPaaaarrrraaaammmmeeeetttteeeerrrrssss

      1.      The first parameter is the required name for the
          field    (-name).

      2.      The optional second parameter    is the default
          starting value for the field contents    (-default).

      3.      The optional third parameter is the size of the
          field    in
            characters (-size).

      4.      The optional fourth parameter    is the maximum number
          of characters    the
            field will accept (-maxlength).

          As with all these methods, the field will be
          initialized with its previous    contents from earlier
          invocations of the script.  When the form is



     Page 27                        (printed 10/23/98)






     CCCCGGGGIIII((((3333))))         22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))        CCCCGGGGIIII((((3333))))



          processed, the value of the text field can be
          retrieved with:

             $value    = $query->param('foo');

          If you want to reset it from its initial value after
          the script has been called once, you can do so like
          this:

             $query->param('foo',"I'm taking over this value!");

          NEW AS OF VERSION 2.15: If you don't want the    field
          to take on its previous value, you can force its
          current value    by using the -override (alias -force)
          parameter:

              print $query->textfield(-name=>'field_name',
                          -default=>'starting value',
                          -override=>1,
                          -size=>50,
                          -maxlength=>80);

          JAVASCRIPTING: You can also provide ----oooonnnnCCCChhhhaaaannnnggggeeee,
          ----oooonnnnFFFFooooccccuuuussss, ----oooonnnnBBBBlllluuuurrrr, ----oooonnnnMMMMoooouuuusssseeeeOOOOvvvveeeerrrr, ----oooonnnnMMMMoooouuuusssseeeeOOOOuuuutttt and
          ----oooonnnnSSSSeeeelllleeeecccctttt parameters to register JavaScript event
          handlers.  The onChange handler will be called
          whenever the user changes the    contents of the    text
          field.  You can do text validation if    you like.
          onFocus and onBlur are called    respectively when the
          insertion point moves    into and out of    the text
          field.  onSelect is called when the user changes the
          portion of the text that is selected.

      CCCCRRRREEEEAAAATTTTIIIINNNNGGGG AAAA BBBBIIIIGGGG TTTTEEEEXXXXTTTT FFFFIIIIEEEELLLLDDDD

         print $query->textarea(-name=>'foo',
                    -default=>'starting    value',
                    -rows=>10,
                    -columns=>50);

          -or

         print $query->textarea('foo','starting value',10,50);

      _t_e_x_t_a_r_e_a() is    just like textfield, but it allows you to
      specify rows and columns for a multiline text    entry box.
      You can provide a starting value for the field, which    can be
      long and contain multiple lines.

      JAVASCRIPTING: The ----oooonnnnCCCChhhhaaaannnnggggeeee,    ----oooonnnnFFFFooooccccuuuussss, ----oooonnnnBBBBlllluuuurrrr ,
      ----oooonnnnMMMMoooouuuusssseeeeOOOOvvvveeeerrrr,    ----oooonnnnMMMMoooouuuusssseeeeOOOOuuuutttt, and ----oooonnnnSSSSeeeelllleeeecccctttt parameters are
      recognized.  See _t_e_x_t_f_i_e_l_d().



     Page 28                        (printed 10/23/98)






     CCCCGGGGIIII((((3333))))         22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))        CCCCGGGGIIII((((3333))))



      CCCCRRRREEEEAAAATTTTIIIINNNNGGGG AAAA PPPPAAAASSSSSSSSWWWWOOOORRRRDDDD FFFFIIIIEEEELLLLDDDD

         print $query->password_field(-name=>'secret',
                      -value=>'starting value',
                      -size=>50,
                      -maxlength=>80);
          -or-

         print $query->password_field('secret','starting value',50,80);

      _p_a_s_s_w_o_r_d__f_i_e_l_d() is identical    to _t_e_x_t_f_i_e_l_d(),    except that
      its contents will be starred out on the web page.

      JAVASCRIPTING: The ----oooonnnnCCCChhhhaaaannnnggggeeee,    ----oooonnnnFFFFooooccccuuuussss, ----oooonnnnBBBBlllluuuurrrr,
      ----oooonnnnMMMMoooouuuusssseeeeOOOOvvvveeeerrrr,    ----oooonnnnMMMMoooouuuusssseeeeOOOOuuuutttt and    ----oooonnnnSSSSeeeelllleeeecccctttt parameters are
      recognized.  See _t_e_x_t_f_i_e_l_d().

      CCCCRRRREEEEAAAATTTTIIIINNNNGGGG AAAA FFFFIIIILLLLEEEE UUUUPPPPLLLLOOOOAAAADDDD FFFFIIIIEEEELLLLDDDD

          print $query->filefield(-name=>'uploaded_file',
                      -default=>'starting value',
                      -size=>50,
                      -maxlength=>80);
          -or-

          print $query->filefield('uploaded_file','starting    value',50,80);

      _f_i_l_e_f_i_e_l_d() will return a file upload    field for Netscape 2.0
      browsers.  In    order to take full advantage of    this _y_o_u _m_u_s_t
      _u_s_e _t_h_e _n_e_w _m_u_l_t_i_p_a_r_t    _e_n_c_o_d_i_n_g _s_c_h_e_m_e    for the    form.  You can
      do this either by calling ssssttttaaaarrrrttttffffoooorrrrmmmm(((())))    with an    encoding type
      of $$$$CCCCGGGGIIII::::::::MMMMUUUULLLLTTTTIIIIPPPPAAAARRRRTTTT, or by calling the    new method
      ssssttttaaaarrrrtttt____mmmmuuuullllttttiiiippppaaaarrrrtttt____ffffoooorrrrmmmm(((()))) instead of vanilla ssssttttaaaarrrrttttffffoooorrrrmmmm(((()))).

      PPPPaaaarrrraaaammmmeeeetttteeeerrrrssss

      1.      The first parameter is the required name for the
          field    (-name).

      2.      The optional second parameter    is the starting    value
          for the field    contents to be used as the default
          file name (-default).

          The beta2 version of Netscape    2.0 currently doesn't
          pay any attention to this field, and so the starting
          value    will always be blank.  Worse, the field    loses
          its "sticky" behavior    and forgets its    previous
          contents.  The starting value    field is called    for in
          the HTML specification, however, and possibly    later
          versions of Netscape will honor it.





     Page 29                        (printed 10/23/98)






     CCCCGGGGIIII((((3333))))         22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))        CCCCGGGGIIII((((3333))))



      3.      The optional third parameter is the size of the
          field    in characters (-size).

      4.      The optional fourth parameter    is the maximum number
          of characters    the field will accept (-maxlength).

          When the form    is processed, you can retrieve the
          entered filename by calling _p_a_r_a_m().

             $filename = $query->param('uploaded_file');

          In Netscape Navigator    2.0, the filename that gets
          returned is the full local filename on the rrrreeeemmmmooootttteeee
          uuuusssseeeerrrr''''ssss machine.  If the remote user is on a Unix
          machine, the filename    will follow Unix conventions:

              /path/to/the/file

          On an    MS-DOS/Windows and OS/2    machines, the filename
          will follow DOS conventions:

              C:\PATH\TO\THE\FILE.MSW

          On a Macintosh machine, the filename will follow Mac
          conventions:

              HD 40:Desktop    Folder:Sort Through:Reminders

          The filename returned    is also    a file handle.    You
          can read the contents    of the file using standard
          Perl file reading calls:

              # Read a text    file and print it out
              while    (<$filename>) {
                 print;
              }

              # Copy a binary file to somewhere safe
              open (OUTFILE,">>/usr/local/web/users/feedback");
              while    ($bytesread=read($filename,$buffer,1024)) {
                 print OUTFILE $buffer;
              }

          When a file is uploaded the browser usually sends
          along    some information along with it in the format
          of headers.  The information usually includes    the
          MIME content type.  Future browsers may send other
          information as well (such as modification date and
          size). To retrieve this information, call
          _u_p_l_o_a_d_I_n_f_o().     It returns a reference    to an
          associative array containing all the document
          headers.



     Page 30                        (printed 10/23/98)






     CCCCGGGGIIII((((3333))))         22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))        CCCCGGGGIIII((((3333))))



             $filename = $query->param('uploaded_file');
             $type = $query->uploadInfo($filename)->{'Content-Type'};
             unless    ($type eq 'text/html') {
                die    "HTML FILES ONLY!";
             }

          If you are using a machine that recognizes "text"
          and "binary" data modes, be sure to understand when
          and how to use them (see the Camel book). Otherwise
          you may find that binary files are corrupted during
          file uploads.

          JAVASCRIPTING: The ----oooonnnnCCCChhhhaaaannnnggggeeee,    ----oooonnnnFFFFooooccccuuuussss, ----oooonnnnBBBBlllluuuurrrr,
          ----oooonnnnMMMMoooouuuusssseeeeOOOOvvvveeeerrrr,    ----oooonnnnMMMMoooouuuusssseeeeOOOOuuuutttt and    ----oooonnnnSSSSeeeelllleeeecccctttt parameters
          are recognized.  See _t_e_x_t_f_i_e_l_d() for details.

      CCCCRRRREEEEAAAATTTTIIIINNNNGGGG AAAA PPPPOOOOPPPPUUUUPPPP MMMMEEEENNNNUUUU

         print $query->popup_menu('menu_name',
                      ['eenie','meenie','minie'],
                      'meenie');

        -or-

         %labels = ('eenie'=>'your first choice',
            'meenie'=>'your    second choice',
            'minie'=>'your third choice');
         print $query->popup_menu('menu_name',
                      ['eenie','meenie','minie'],
                      'meenie',\%labels);

          -or (named parameter style)-

         print $query->popup_menu(-name=>'menu_name',
                      -values=>['eenie','meenie','minie'],
                      -default=>'meenie',
                      -labels=>\%labels);

      _p_o_p_u_p__m_e_n_u() creates a menu.

      1.      The required first argument is the menu's name
          (-name).

      2.      The required second argument (-values) is an array
          rrrreeeeffffeeeerrrreeeennnncccceeee containing the list    of menu    items in the
          menu.     You can pass the method an anonymous array,
          as shown in the example, or a    reference to a named
          array, such as "\@foo".

      3.      The optional third parameter (-default) is the name
          of the default menu choice.  If not specified, the
          first    item will be the default.  The values of the



     Page 31                        (printed 10/23/98)






     CCCCGGGGIIII((((3333))))         22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))        CCCCGGGGIIII((((3333))))



          previous choice will be maintained across queries.

      4.      The optional fourth parameter    (-labels) is provided
          for people who want to use different values for the
          user-visible label inside the    popup menu nd the
          value    returned to your script.  It's a pointer to an
          associative array relating menu values to user-
          visible labels.  If you leave    this parameter blank,
          the menu values will be displayed by default.     (You
          can also leave a label undefined if you want to).

          When the form    is processed, the selected value of
          the popup menu can be    retrieved using:

            $popup_menu_value = $query->param('menu_name');

          JAVASCRIPTING: _p_o_p_u_p__m_e_n_u() recognizes the following
          event    handlers:  ----oooonnnnCCCChhhhaaaannnnggggeeee, ----oooonnnnFFFFooooccccuuuussss,    ----oooonnnnMMMMoooouuuusssseeeeOOOOvvvveeeerrrr,
          ----oooonnnnMMMMoooouuuusssseeeeOOOOuuuutttt, and ----oooonnnnBBBBlllluuuurrrr.  See the _t_e_x_t_f_i_e_l_d()
          section for details on when these handlers are
          called.

      CCCCRRRREEEEAAAATTTTIIIINNNNGGGG AAAA SSSSCCCCRRRROOOOLLLLLLLLIIIINNNNGGGG LLLLIIIISSSSTTTT

         print $query->scrolling_list('list_name',
                      ['eenie','meenie','minie','moe'],
                      ['eenie','moe'],5,'true');
        -or-

         print $query->scrolling_list('list_name',
                      ['eenie','meenie','minie','moe'],
                      ['eenie','moe'],5,'true',
                      \%labels);

          -or-

         print $query->scrolling_list(-name=>'list_name',
                      -values=>['eenie','meenie','minie','moe'],
                      -default=>['eenie','moe'],
                      -size=>5,
                      -multiple=>'true',
                      -labels=>\%labels);

      _s_c_r_o_l_l_i_n_g__l_i_s_t() creates a scrolling list.

      PPPPaaaarrrraaaammmmeeeetttteeeerrrrssss::::

      1.      The first and    second arguments are the list name
          (-name) and values (-values).     As in the popup menu,
          the second argument should be    an array reference.





     Page 32                        (printed 10/23/98)






     CCCCGGGGIIII((((3333))))         22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))        CCCCGGGGIIII((((3333))))



      2.      The optional third argument (-default) can be    either
          a reference to a list    containing the values to be
          selected by default, or can be a single value    to
          select.  If this argument is missing or undefined,
          then nothing is selected when    the list first
          appears.  In the named parameter version, you    can
          use the synonym "-defaults" for this parameter.

      3.      The optional fourth argument is the size of the list
          (-size).

      4.      The optional fifth argument can be set to true to
          allow    multiple simultaneous selections (-multiple).
          Otherwise only one selection will be allowed at a
          time.

      5.      The optional sixth argument is a pointer to an
          associative array containing long user-visible
          labels for the list items (-labels).    If not
          provided, the    values will be displayed.

          When this form is processed, all selected list items
          will be returned as a    list under the parameter name
          'list_name'.    The values of the selected items can
          be retrieved with:

            @selected = $query->param('list_name');


          JAVASCRIPTING: _s_c_r_o_l_l_i_n_g__l_i_s_t() recognizes the
          following event handlers: ----oooonnnnCCCChhhhaaaannnnggggeeee, ----oooonnnnFFFFooooccccuuuussss,
          ----oooonnnnMMMMoooouuuusssseeeeOOOOvvvveeeerrrr,    ----oooonnnnMMMMoooouuuusssseeeeOOOOuuuutttt and    ----oooonnnnBBBBlllluuuurrrr.  See
          _t_e_x_t_f_i_e_l_d() for the description of when these
          handlers are called.

      CCCCRRRREEEEAAAATTTTIIIINNNNGGGG AAAA GGGGRRRROOOOUUUUPPPP OOOOFFFF RRRREEEELLLLAAAATTTTEEEEDDDD CCCCHHHHEEEECCCCKKKKBBBBOOOOXXXXEEEESSSS

         print $query->checkbox_group(-name=>'group_name',
                      -values=>['eenie','meenie','minie','moe'],
                      -default=>['eenie','moe'],
                      -linebreak=>'true',
                      -labels=>\%labels);

         print $query->checkbox_group('group_name',
                      ['eenie','meenie','minie','moe'],
                      ['eenie','moe'],'true',\%labels);

         HTML3-COMPATIBLE BROWSERS ONLY:







     Page 33                        (printed 10/23/98)






     CCCCGGGGIIII((((3333))))         22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))        CCCCGGGGIIII((((3333))))



         print $query->checkbox_group(-name=>'group_name',
                      -values=>['eenie','meenie','minie','moe'],
                      -rows=2,-columns=>2);


      _c_h_e_c_k_b_o_x__g_r_o_u_p() creates a list of checkboxes    that are
      related by the same name.

      PPPPaaaarrrraaaammmmeeeetttteeeerrrrssss::::

      1.      The first and    second arguments are the checkbox name
          and values, respectively (-name and -values).     As in
          the popup menu, the second argument should be    an
          array    reference.  These values are used for the
          user-readable    labels printed next to the checkboxes
          as well as for the values passed to your script in
          the query string.

      2.      The optional third argument (-default) can be    either
          a reference to a list    containing the values to be
          checked by default, or can be    a single value to
          checked.  If this argument is    missing    or undefined,
          then nothing is selected when    the list first
          appears.

      3.      The optional fourth argument (-linebreak) can    be set
          to true to place line    breaks between the checkboxes
          so that they appear as a vertical list.  Otherwise,
          they will be strung together on a horizontal line.

      4.      The optional fifth argument is a pointer to an
          associative array relating the checkbox values to
          the user-visible labels that will be printed next to
          them (-labels).  If not provided, the    values will be
          used as the default.

      5.      HHHHTTTTMMMMLLLL3333----ccccoooommmmppppaaaattttiiiibbbblllleeee bbbbrrrroooowwwwsssseeeerrrrssss (such as Netscape) can
          take advantage of the    optional parameters ----rrrroooowwwwssss, and
          ----ccccoooolllluuuummmmnnnnssss.  These parameters cause _c_h_e_c_k_b_o_x__g_r_o_u_p()
          to return an HTML3 compatible    table containing the
          checkbox group formatted with    the specified number
          of rows and columns.    You can    provide    just the
          -columns parameter if    you wish; checkbox_group will
          calculate the    correct    number of rows for you.

          To include row and column headings in    the returned
          table, you can use the ----rrrroooowwwwhhhheeeeaaaaddddeeeerrrrssss and ----ccccoooollllhhhheeeeaaaaddddeeeerrrrssss
          parameters.  Both of these accept a pointer to an
          array    of headings to use.  The headings are just
          decorative.  They don't reorganize the
          interpretation of the    checkboxes -- they're still a
          single named unit.



     Page 34                        (printed 10/23/98)






     CCCCGGGGIIII((((3333))))         22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))        CCCCGGGGIIII((((3333))))



          When the form    is processed, all checked boxes    will
          be returned as a list    under the parameter name
          'group_name'.     The values of the "on"    checkboxes can
          be retrieved with:

            @turned_on = $query->param('group_name');

          The value returned by    _c_h_e_c_k_b_o_x__g_r_o_u_p() is actually
          an array of button elements.    You can    capture    them
          and use them within tables, lists, or    in other
          creative ways:

              @h = $query->checkbox_group(-name=>'group_name',-values=>\@values);
              &use_in_creative_way(@h);

          JAVASCRIPTING: _c_h_e_c_k_b_o_x__g_r_o_u_p() recognizes the
          ----oooonnnnCCCClllliiiicccckkkk parameter.  This specifies a    JavaScript
          code fragment    or function call to be executed    every
          time the user    clicks on any of the buttons in    the
          group.  You can retrieve the identity    of the
          particular button clicked on using the "this"
          variable.

      CCCCRRRREEEEAAAATTTTIIIINNNNGGGG AAAA SSSSTTTTAAAANNNNDDDDAAAALLLLOOOONNNNEEEE    CCCCHHHHEEEECCCCKKKKBBBBOOOOXXXX

          print $query->checkbox(-name=>'checkbox_name',
                     -checked=>'checked',
                     -value=>'ON',
                     -label=>'CLICK ME');

          -or-

          print $query->checkbox('checkbox_name','checked','ON','CLICK ME');

      _c_h_e_c_k_b_o_x() is    used to    create an isolated checkbox that isn't
      logically related to any others.

      PPPPaaaarrrraaaammmmeeeetttteeeerrrrssss::::

      1.      The first parameter is the required name for the
          checkbox (-name).  It    will also be used for the
          user-readable    label printed next to the checkbox.

      2.      The optional second parameter    (-checked) specifies
          that the checkbox is turned on by default.  Synonyms
          are -selected    and -on.

      3.      The optional third parameter (-value)    specifies the
          value    of the checkbox    when it    is checked.  If    not
          provided, the    word "on" is assumed.





     Page 35                        (printed 10/23/98)






     CCCCGGGGIIII((((3333))))         22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))        CCCCGGGGIIII((((3333))))



      4.      The optional fourth parameter    (-label) is the    user-
          readable label to be attached    to the checkbox.  If
          not provided,    the checkbox name is used.

          The value of the checkbox can    be retrieved using:

              $turned_on = $query->param('checkbox_name');

          JAVASCRIPTING: _c_h_e_c_k_b_o_x() recognizes the ----oooonnnnCCCClllliiiicccckkkk
          parameter.  See _c_h_e_c_k_b_o_x__g_r_o_u_p() for further
          details.

      CCCCRRRREEEEAAAATTTTIIIINNNNGGGG AAAA RRRRAAAADDDDIIIIOOOO BBBBUUUUTTTTTTTTOOOONNNN GGGGRRRROOOOUUUUPPPP

         print $query->radio_group(-name=>'group_name',
                       -values=>['eenie','meenie','minie'],
                       -default=>'meenie',
                       -linebreak=>'true',
                       -labels=>\%labels);

          -or-

         print $query->radio_group('group_name',['eenie','meenie','minie'],
                            'meenie','true',\%labels);

         HTML3-COMPATIBLE BROWSERS ONLY:

         print $query->radio_group(-name=>'group_name',
                       -values=>['eenie','meenie','minie','moe'],
                       -rows=2,-columns=>2);

      _r_a_d_i_o__g_r_o_u_p()    creates    a set of logically-related radio
      buttons (turning one member of the group on turns the    others
      off)

      PPPPaaaarrrraaaammmmeeeetttteeeerrrrssss::::

      1.      The first argument is    the name of the    group and is
          required (-name).

      2.      The second argument (-values)    is the list of values
          for the radio    buttons.  The values and the labels
          that appear on the page are identical.  Pass an
          array    _r_e_f_e_r_e_n_c_e in the second    argument, either using
          an anonymous array, as shown,    or by referencing a
          named    array as in "\@foo".

      3.      The optional third parameter (-default) is the name
          of the default button    to turn    on. If not specified,
          the first item will be the default.  You can provide
          a nonexistent    button name, such as "-" to start up
          with no buttons selected.



     Page 36                        (printed 10/23/98)






     CCCCGGGGIIII((((3333))))         22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))        CCCCGGGGIIII((((3333))))



      4.      The optional fourth parameter    (-linebreak) can be
          set to 'true'    to put line breaks between the
          buttons, creating a vertical list.

      5.      The optional fifth parameter (-labels) is a pointer
          to an    associative array relating the radio button
          values to user-visible labels    to be used in the
          display.  If not provided, the values    themselves are
          displayed.

      6.      HHHHTTTTMMMMLLLL3333----ccccoooommmmppppaaaattttiiiibbbblllleeee bbbbrrrroooowwwwsssseeeerrrrssss (such as Netscape) can
          take advantage of the    optional parameters ----rrrroooowwwwssss, and
          ----ccccoooolllluuuummmmnnnnssss.  These parameters cause _r_a_d_i_o__g_r_o_u_p() to
          return an HTML3 compatible table containing the
          radio    group formatted    with the specified number of
          rows and columns.  You can provide just the -columns
          parameter if you wish; radio_group will calculate
          the correct number of    rows for you.

          To include row and column headings in    the returned
          table, you can use the ----rrrroooowwwwhhhheeeeaaaaddddeeeerrrr and    ----ccccoooollllhhhheeeeaaaaddddeeeerrrr
          parameters.  Both of these accept a pointer to an
          array    of headings to use.  The headings are just
          decorative.  They don't reorganize the interpetation
          of the radio buttons -- they're still    a single named
          unit.

          When the form    is processed, the selected radio
          button can be    retrieved using:

            $which_radio_button = $query->param('group_name');

          The value returned by    _r_a_d_i_o__g_r_o_u_p() is actually an
          array    of button elements.  You can capture them and
          use them within tables, lists, or in other creative
          ways:

              @h = $query->radio_group(-name=>'group_name',-values=>\@values);
              &use_in_creative_way(@h);


      CCCCRRRREEEEAAAATTTTIIIINNNNGGGG AAAA SSSSUUUUBBBBMMMMIIIITTTT BBBBUUUUTTTTTTTTOOOONNNN

         print $query->submit(-name=>'button_name',
                  -value=>'value');

          -or-

         print $query->submit('button_name','value');

      _s_u_b_m_i_t() will    create the query submission button.  Every
      form should have one of these.



     Page 37                        (printed 10/23/98)






     CCCCGGGGIIII((((3333))))         22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))        CCCCGGGGIIII((((3333))))



      PPPPaaaarrrraaaammmmeeeetttteeeerrrrssss::::

      1.      The first argument (-name) is    optional.  You can
          give the button a name if you    have several
          submission buttons in    your form and you want to
          distinguish between them.  The name will also    be
          used as the user-visible label.  Be aware that a few
          older    browsers don't deal with this correctly    and
          nnnneeeevvvveeeerrrr    send back a value from a button.

      2.      The second argument (-value) is also optional.  This
          gives    the button a value that    will be    passed to your
          script in the    query string.

          You can figure out which button was pressed by using
          different values for each one:

               $which_one = $query->param('button_name');

          JAVASCRIPTING: _r_a_d_i_o__g_r_o_u_p() recognizes the ----oooonnnnCCCClllliiiicccckkkk
          parameter.  See _c_h_e_c_k_b_o_x__g_r_o_u_p() for further
          details.

      CCCCRRRREEEEAAAATTTTIIIINNNNGGGG AAAA RRRREEEESSSSEEEETTTT BBBBUUUUTTTTTTTTOOOONNNN

         print $query->reset

      _r_e_s_e_t() creates the "reset" button.  Note that it restores
      the form to its value    from the last time the script was
      called, NOT necessarily to the defaults.

      CCCCRRRREEEEAAAATTTTIIIINNNNGGGG AAAA DDDDEEEEFFFFAAAAUUUULLLLTTTT BBBBUUUUTTTTTTTTOOOONNNN

         print $query->defaults('button_label')

      _d_e_f_a_u_l_t_s() creates a button that, when invoked, will cause
      the form to be completely reset to its defaults, wiping out
      all the changes the user ever    made.

      CCCCRRRREEEEAAAATTTTIIIINNNNGGGG AAAA HHHHIIIIDDDDDDDDEEEENNNN FFFFIIIIEEEELLLLDDDD

          print    $query->hidden(-name=>'hidden_name',
                       -default=>['value1','value2'...]);

              -or-

          print    $query->hidden('hidden_name','value1','value2'...);

      _h_i_d_d_e_n() produces a text field that can't be seen by the
      user.     It is useful for passing state    variable information
      from one invocation of the script to the next.




     Page 38                        (printed 10/23/98)






     CCCCGGGGIIII((((3333))))         22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))        CCCCGGGGIIII((((3333))))



      PPPPaaaarrrraaaammmmeeeetttteeeerrrrssss::::

      1.      The first argument is    required and specifies the
          name of this field (-name).

      2.      The second argument is also required and specifies
          its value (-default).     In the    named parameter    style
          of calling, you can provide a    single value here or a
          reference to a whole list

          Fetch    the value of a hidden field this way:

               $hidden_value = $query->param('hidden_name');

          Note,    that just like all the other form elements,
          the value of a hidden    field is "sticky".  If you
          want to replace a hidden field with some other
          values after the script has been called once you'll
          have to do it    manually:

               $query->param('hidden_name','new','values','here');


      CCCCRRRREEEEAAAATTTTIIIINNNNGGGG AAAA CCCCLLLLIIIICCCCKKKKAAAABBBBLLLLEEEE IIIIMMMMAAAAGGGGEEEE BBBBUUUUTTTTTTTTOOOONNNN

           print $query->image_button(-name=>'button_name',
                      -src=>'/source/URL',
                      -align=>'MIDDLE');

          -or-

           print $query->image_button('button_name','/source/URL','MIDDLE');

      _i_m_a_g_e__b_u_t_t_o_n() produces a clickable image.  When it's
      clicked on the position of the click is returned to your
      script as "button_name.x" and    "button_name.y", where
      "button_name"    is the name you've assigned to it.

      JAVASCRIPTING: _i_m_a_g_e__b_u_t_t_o_n()    recognizes the ----oooonnnnCCCClllliiiicccckkkk
      parameter.  See _c_h_e_c_k_b_o_x__g_r_o_u_p() for further details.

      PPPPaaaarrrraaaammmmeeeetttteeeerrrrssss::::

      1.      The first argument (-name) is    required and specifies
          the name of this field.

      2.      The second argument (-src) is    also required and
          specifies the    URL

     may be TOP, BOTTOM    or MIDDLE
      3. The third option (-align, optional) is an alignment type, and




     Page 39                        (printed 10/23/98)






     CCCCGGGGIIII((((3333))))         22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))        CCCCGGGGIIII((((3333))))



          Fetch    the value of the button    this way:
               $x = $query->_p_a_r_a_m('button_name.x');
               $y = $query->_p_a_r_a_m('button_name.y');

      CCCCRRRREEEEAAAATTTTIIIINNNNGGGG AAAA JJJJAAAAVVVVAAAASSSSCCCCRRRRIIIIPPPPTTTT    AAAACCCCTTTTIIIIOOOONNNN BBBBUUUUTTTTTTTTOOOONNNN

           print $query->button(-name=>'button_name',
                    -value=>'user visible label',
                    -onClick=>"do_something()");

          -or-

           print $query->button('button_name',"do_something()");

      _b_u_t_t_o_n() produces a button that is compatible    with Netscape
      2.0's    JavaScript.  When it's pressed the fragment of
      JavaScript code pointed to by    the ----oooonnnnCCCClllliiiicccckkkk parameter will be
      executed.  On    non-Netscape browsers this form    element    will
      probably not even display.

     NNNNEEEETTTTSSSSCCCCAAAAPPPPEEEE CCCCOOOOOOOOKKKKIIIIEEEESSSS
      Netscape browsers versions 1.1 and higher support a so-
      called "cookie" designed to help maintain state within a
      browser session.  CGI.pm has several methods that support
      cookies.

      A cookie is a    name=value pair    much like the named parameters
      in a CGI query string.  CGI scripts create one or more
      cookies and send them    to the browser in the HTTP header.
      The browser maintains    a list of cookies that belong to a
      particular Web server, and returns them to the CGI script
      during subsequent interactions.

      In addition to the required name=value pair, each cookie has
      several optional attributes:

      1. an    expiration time
          This is a time/date string (in a special GMT format)
          that indicates when a    cookie expires.     The cookie
          will be saved    and returned to    your script until this
          expiration date is reached if    the user exits
          Netscape and restarts    it.  If    an expiration date
          isn't    specified, the cookie will remain active until
          the user quits Netscape.

      2. a domain
          This is a partial or complete    domain name for    which
          the cookie is    valid.    The browser will return    the
          cookie to any    host that matches the partial domain
          name.     For example, if you specify a domain name of
          ".capricorn.com", then Netscape will return the
          cookie to Web    servers    running    on any of the machines



     Page 40                        (printed 10/23/98)






     CCCCGGGGIIII((((3333))))         22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))        CCCCGGGGIIII((((3333))))



          "www.capricorn.com", "www2.capricorn.com",
          "feckless.capricorn.com", etc.  Domain names must
          contain at least two periods to prevent attempts to
          match    on top level domains like ".edu".  If no
          domain is specified, then the    browser    will only
          return the cookie to servers on the host the cookie
          originated from.

      3. a path
          If you provide a cookie path attribute, the browser
          will check it    against    your script's URL before
          returning the    cookie.     For example, if you specify
          the path "/cgi-bin", then the    cookie will be
          returned to each of the scripts "/cgi-bin/tally.pl",
          "/cgi-bin/order.pl", and "/cgi-
          bin/customer_service/complain.pl", but not to    the
          script "/cgi-private/site_admin.pl".    By default,
          path is set to "/", which causes the cookie to be
          sent to any CGI script on your site.

      4. a "secure"    flag
          If the "secure" attribute is set, the    cookie will
          only be sent to your script if the CGI request is
          occurring on a secure    channel, such as SSL.

          The interface    to Netscape cookies is the ccccooooooookkkkiiiieeee(((())))
          method:

              $cookie =    $query->cookie(-name=>'sessionID',
                           -value=>'xyzzy',
                           -expires=>'+1h',
                           -path=>'/cgi-bin/database',
                           -domain=>'.capricorn.org',
                           -secure=>1);
              print $query->header(-cookie=>$cookie);

          ccccooooooookkkkiiiieeee(((()))) creates a new cookie.  Its parameters
          include:

      ----nnnnaaaammmmeeee      The name of the cookie (required).  This can be any
          string at all.  Although Netscape limits its cookie
          names    to non-whitespace alphanumeric characters,
          CGI.pm removes this restriction by escaping and
          unescaping cookies behind the    scenes.

      ----vvvvaaaalllluuuueeee  The value of the cookie.  This can be    any scalar
          value, array reference, or even associative array
          reference.  For example, you can store an entire
          associative array into a cookie this way:

              $cookie=$query->cookie(-name=>'family    information',
                         -value=>\%childrens_ages);



     Page 41                        (printed 10/23/98)






     CCCCGGGGIIII((((3333))))         22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))        CCCCGGGGIIII((((3333))))



      ----ppppaaaatttthhhh      The optional partial path for    which this cookie will
          be valid, as described above.

      ----ddddoooommmmaaaaiiiinnnn The optional partial domain for which    this cookie
          will be valid, as described above.

      ----eeeexxxxppppiiiirrrreeeessss
          The optional expiration date for this    cookie.     The
          format is as described in the    section    on the
          hhhheeeeaaaaddddeeeerrrr(((()))) method:

              "+1h"     one hour from now


      ----sssseeeeccccuuuurrrreeee If set to true, this cookie will only    be used    within
          a secure SSL session.

          The cookie created by    _c_o_o_k_i_e() must be incorporated
          into the HTTP    header within the string returned by
          the _h_e_a_d_e_r() method:

              print    $query->header(-cookie=>$my_cookie);

          To create multiple cookies, give _h_e_a_d_e_r() an array
          reference:

              $cookie1 = $query->cookie(-name=>'riddle_name',
                            -value=>"The Sphynx's Question");
              $cookie2 = $query->cookie(-name=>'answers',
                            -value=>\%answers);
              print    $query->header(-cookie=>[$cookie1,$cookie2]);

          To retrieve a    cookie,    request    it by name by calling
          _c_o_o_k_i_e() method without the ----vvvvaaaalllluuuueeee parameter:

              use CGI;
              $query = new CGI;
              %answers = $query->cookie(-name=>'answers');
              # $query->cookie('answers') will work    too!

          The cookie and CGI namespaces    are separate.  If you
          have a parameter named 'answers' and a cookie    named
          'answers', the values    retrieved by _p_a_r_a_m() and
          _c_o_o_k_i_e() are independent of each other.  However,
          it's simple to turn a    CGI parameter into a cookie,
          and vice-versa:

             # turn a CGI parameter into a cookie
             $c=$q->cookie(-name=>'answers',-value=>[$q->param('answers')]);
             # vice-versa
             $q->param(-name=>'answers',-value=>[$q->cookie('answers')]);




     Page 42                        (printed 10/23/98)






     CCCCGGGGIIII((((3333))))         22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))        CCCCGGGGIIII((((3333))))



          See the ccccooooooookkkkiiiieeee....ccccggggiiii example script for    some ideas on
          how to use cookies effectively.

          NNNNOOOOTTTTEEEE::::    There appear to    be some    (undocumented)
          restrictions on Netscape cookies.  In    Netscape 2.01,
          at least, I haven't been able    to set more than three
          cookies at a time.  There may    also be    limits on the
          length of cookies.  If you need to store a lot of
          information, it's probably better to create a    unique
          session ID, store it in a cookie, and    use the
          session ID to    locate an external file/database saved
          on the server's side of the connection.

     WWWWOOOORRRRKKKKIIIINNNNGGGG WWWWIIIITTTTHHHH NNNNEEEETTTTSSSSCCCCAAAAPPPPEEEE FFFFRRRRAAAAMMMMEEEESSSS
      It's possible    for CGI.pm scripts to write into several
      browser panels and windows using Netscape's frame mechanism.
      There    are three techniques for defining new frames
      programmatically:

      1. Create a <Frameset> document
          After    writing    out the    HTTP header, instead of
          creating a standard HTML document using the
          _s_t_a_r_t__h_t_m_l() call, create a <FRAMESET> document that
          defines the frames on    the page.  Specify your
          _s_c_r_i_p_t(s) (with appropriate parameters) as the SRC
          for each of the frames.

          There    is no specific support for creating <FRAMESET>
          sections in CGI.pm, but the HTML is very simple to
          write.  See the frame    documentation in Netscape's
          home pages for details

            http://home.netscape.com/assist/net_sites/frames.html


      2. Specify the destination for the document in the HTTP header
          You may provide a ----ttttaaaarrrrggggeeeetttt parameter to the _h_e_a_d_e_r()
          method:

              print $q->_h_e_a_d_e_r(-target=>'ResultsWindow');

          This will tell Netscape to load the output of    your
          script into the frame    named "ResultsWindow".    If a
          frame    of that    name doesn't already exist, Netscape
          will pop up a    new window and load your script's
          document into    that.  There are a number of magic
          names    that you can use for targets.  See the frame
          documents on Netscape's home pages for details.

      3. Specify the destination for the document in the <FORM> tag
          You can specify the frame to load in the FORM    tag
          itself.  With    CGI.pm it looks    like this:



     Page 43                        (printed 10/23/98)






     CCCCGGGGIIII((((3333))))         22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))        CCCCGGGGIIII((((3333))))



              print $q->startform(-target=>'ResultsWindow');

          When your script is reinvoked    by the form, its
          output will be loaded    into the frame named
          "ResultsWindow".  If one doesn't already exist a new
          window will be created.

          The script "frameset.cgi" in the examples directory
          shows    one way    to create pages    in which the fill-out
          form and the response    live in    side-by-side frames.

     LLLLIIIIMMMMIIIITTTTEEEEDDDD SSSSUUUUPPPPPPPPOOOORRRRTTTT FFFFOOOORRRR CCCCAAAASSSSCCCCAAAADDDDIIIINNNNGGGG SSSSTTTTYYYYLLLLEEEE SSSSHHHHEEEEEEEETTTTSSSS
      CGI.pm has limited support for HTML3's cascading style
      sheets (css).     To incorporate    a stylesheet into your
      document, pass the _s_t_a_r_t__h_t_m_l() method a ----ssssttttyyyylllleeee parameter.
      The value of this parameter may be a scalar, in which    case
      it is    incorporated directly into a <STYLE> section, or it
      may be a hash    reference.  In the latter case you should
      provide the hash with    one or more of ----ssssrrrrcccc or ----ccccooooddddeeee.  ----ssssrrrrcccc
      points to a URL where    an externally-defined stylesheet can
      be found.  ----ccccooooddddeeee points to a scalar value to be incorporated
      into a <STYLE> section.  Style definitions in    ----ccccooooddddeeee override
      similarly-named ones in ----ssssrrrrcccc,    hence the name "cascading."

      You may also specify the type    of the stylesheet by adding
      the optional ----ttttyyyyppppeeee parameter to the hash pointed to by
      ----ssssttttyyyylllleeee.  If not specified, the style defaults    to 'text/css'.

      To refer to a    style within the body of your document,    add
      the ----ccccllllaaaassssssss parameter to any HTML element:

          print h1({-class=>'Fancy'},'Welcome to the Party');

      Or define styles on the fly with the ----ssssttttyyyylllleeee parameter:

          print h1({-style=>'Color:    red;'},'Welcome    to Hell');

      You may also use the new ssssppppaaaannnn(((()))) element to apply a style to
      a section of text:

          print span({-style=>'Color: red;'},
             h1('Welcome to    Hell'),
             "Where    did that handbasket get    to?"
             );

      Note that you    must import the    ":html3" definitions to    have
      the ssssppppaaaannnn(((()))) method available.    Here's a quick and dirty
      example of using CSS's.  See the CSS specification at
      http://www.w3.org/pub/WWW/TR/Wd-css-1.html for more
      information.

          use CGI qw/:standard :html3/;



     Page 44                        (printed 10/23/98)






     CCCCGGGGIIII((((3333))))         22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))        CCCCGGGGIIII((((3333))))



          #here's a    stylesheet incorporated    directly into the page
          $newStyle=<<END;
          <!--
          P.Tip {
          margin-right:    50pt;
          margin-left: 50pt;
          color: red;
          }
          P.Alert {
          font-size: 30pt;
          font-family: sans-serif;
        color: red;
          }
          -->
          END
          print header();
          print start_html(    -title=>'CGI with Style',
                -style=>{-src=>'http://www.capricorn.com/style/st1.css',
                     -code=>$newStyle}
                   );
          print h1('CGI with Style'),
            p({-class=>'Tip'},
              "Better read the cascading style sheet spec before playing with this!"),
            span({-style=>'color: magenta'},
             "Look Mom, no hands!",
             p(),
             "Whooo    wee!"
             );
          print end_html;


     DDDDEEEEBBBBUUUUGGGGGGGGIIIINNNNGGGG
      If you are running the script    from the command line or in
      the perl debugger, you can pass the script a list of
      keywords or parameter=value pairs on the command line    or
      from standard    input (you don't have to worry about tricking
      your script into reading from    environment variables).     You
      can pass keywords like this:

          your_script.pl keyword1 keyword2 keyword3

      or this:

         your_script.pl keyword1+keyword2+keyword3

      or this:

          your_script.pl name1=value1 name2=value2

      or this:

          your_script.pl name1=value1&name2=value2



     Page 45                        (printed 10/23/98)






     CCCCGGGGIIII((((3333))))         22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))        CCCCGGGGIIII((((3333))))



      or even as newline-delimited parameters on standard input.

      When debugging, you can use quotes and backslashes to    escape
      characters in    the familiar shell manner, letting you place
      spaces and other funny characters in your parameter=value
      pairs:

         your_script.pl "name1='I am a long    value'"    "name2=two\ words"


      DDDDUUUUMMMMPPPPIIIINNNNGGGG OOOOUUUUTTTT AAAALLLLLLLL TTTTHHHHEEEE NNNNAAAAMMMMEEEE////VVVVAAAALLLLUUUUEEEE PPPPAAAAIIIIRRRRSSSS

      The _d_u_m_p() method produces a string consisting of all    the
      query's name/value pairs formatted nicely as a nested    list.
      This is useful for debugging purposes:

          print $query->dump


      Produces something that looks    like:

          <UL>
          <LI>name1
          <UL>
          <LI>value1
          <LI>value2
          </UL>
          <LI>name2
          <UL>
          <LI>value1
          </UL>
          </UL>

      You can pass a value of 'true' to _d_u_m_p() in order to get it
      to print the results out as plain text, suitable for
      incorporating    into a <PRE> section.

      As a shortcut, as of version 1.56 you    can interpolate    the
      entire CGI object into a string and it will be replaced with
      the a    nice HTML dump shown above:

          $query=new CGI;
          print "<H2>Current Values</H2> $query\n";


     FFFFEEEETTTTCCCCHHHHIIIINNNNGGGG EEEENNNNVVVVIIIIRRRROOOONNNNMMMMEEEENNNNTTTT VVVVAAAARRRRIIIIAAAABBBBLLLLEEEESSSS
      Some of the more useful environment variables    can be fetched
      through this interface.  The methods are as follows:

      aaaacccccccceeeepppptttt(((())))
          Return a list    of MIME    types that the remote browser
          accepts. If you give this method a single argument



     Page 46                        (printed 10/23/98)






     CCCCGGGGIIII((((3333))))         22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))        CCCCGGGGIIII((((3333))))



          corresponding    to a MIME type,    as in
          $query->_a_c_c_e_p_t('text/html'), it will return a
          floating point value corresponding to    the browser's
          preference for this type from    0.0 (don't want) to
          1.0.    Glob types (e.g. text/*) in the    browser's
          accept list are handled correctly.

      rrrraaaawwww____ccccooooooookkkkiiiieeee(((())))
          Returns the HTTP_COOKIE variable, an HTTP extension
          implemented by Netscape browsers version 1.1 and
          higher.  Cookies have    a special format, and this
          method call just returns the raw form    (?cookie
          dough).  See _c_o_o_k_i_e()    for ways of setting and
          retrieving cooked cookies.

          Called with no parameters, _r_a_w__c_o_o_k_i_e() returns the
          packed cookie    structure.  You    can separate it    into
          individual cookies by    splitting on the character
          sequence "; ".  Called with the name of a cookie,
          retrieves the    uuuunnnneeeessssccccaaaappppeeeedddd form of the cookie.  You can
          use the regular _c_o_o_k_i_e() method to get the names, or
          use the _r_a_w__f_e_t_c_h() method from the CGI::Cookie
          module.

      uuuusssseeeerrrr____aaaaggggeeeennnntttt(((())))
          Returns the HTTP_USER_AGENT variable.     If you    give
          this method a    single argument, it will attempt to
          pattern match    on it, allowing    you to do something
          like $query->_u_s_e_r__a_g_e_n_t(netscape);

      ppppaaaatttthhhh____iiiinnnnffffoooo(((())))
          Returns additional path information from the script
          URL.    E.G. fetching /cgi-
          bin/your_script/additional/stuff will    result in
          $query->_p_a_t_h__i_n_f_o() returning    "additional/stuff".

          NOTE:    The Microsoft Internet Information Server is
          broken with respect to additional path information.
          If you use the Perl DLL library, the IIS server will
          attempt to execute the additional path information
          as a Perl script.  If    you use    the ordinary file
          associations mapping,    the path information will be
          present in the environment, but incorrect.  The best
          thing    to do is to avoid using    additional path
          information in CGI scripts destined for use with
          IIS.

      ppppaaaatttthhhh____ttttrrrraaaannnnssssllllaaaatttteeeedddd(((())))
          As per _p_a_t_h__i_n_f_o() but returns the additional    path
          information translated into a    physical path, e.g.
          "/usr/local/etc/httpd/htdocs/additional/stuff".




     Page 47                        (printed 10/23/98)






     CCCCGGGGIIII((((3333))))         22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))        CCCCGGGGIIII((((3333))))



          The Microsoft    IIS is broken with respect to the
          translated path as well.

      rrrreeeemmmmooootttteeee____hhhhoooosssstttt(((())))
          Returns either the remote host name or IP address.
          if the former    is unavailable.

     refering scripts.
      ssssccccrrrriiiipppptttt____nnnnaaaammmmeeee(((())))    Return the script name as a partial URL, for self-

      rrrreeeeffffeeeerrrreeeerrrr(((())))
          Return the URL of the    page the browser was viewing
          prior    to fetching your script.  Not available    for
          all browsers.

      aaaauuuutttthhhh____ttttyyyyppppeeee (((())))
          Return the authorization/verification    method in use
          for this script, if any.

      sssseeeerrrrvvvveeeerrrr____nnnnaaaammmmeeee (((())))
          Returns the name of the server, usually the
          machine's host name.

      vvvviiiirrrrttttuuuuaaaallll____hhhhoooosssstttt (((())))
          When using virtual hosts, returns the    name of    the
          host that the    browser    attempted to contact

      sssseeeerrrrvvvveeeerrrr____ssssooooffffttttwwwwaaaarrrreeee (((())))
          Returns the server software and version number.

      rrrreeeemmmmooootttteeee____uuuusssseeeerrrr (((())))
          Return the authorization/verification    name used for
          user verification, if    this script is protected.

      uuuusssseeeerrrr____nnnnaaaammmmeeee (((())))
          Attempt to obtain the    remote user's name, using a
          variety of different techniques.  This only works
          with older browsers such as Mosaic.  Netscape    does
          not reliably report the user name!

      rrrreeeeqqqquuuueeeesssstttt____mmmmeeeetttthhhhoooodddd(((())))
          Returns the method used to access your script,
          usually one of 'POST', 'GET' or 'HEAD'.

     UUUUSSSSIIIINNNNGGGG NNNNPPPPHHHH SSSSCCCCRRRRIIIIPPPPTTTTSSSS
      NPH, or "no-parsed-header", scripts bypass the server
      completely by    sending    the complete HTTP header directly to
      the browser.    This has slight    performance benefits, but is
      of most use for taking advantage of HTTP extensions that are
      not directly supported by your server, such as server    push
      and PICS headers.




     Page 48                        (printed 10/23/98)






     CCCCGGGGIIII((((3333))))         22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))        CCCCGGGGIIII((((3333))))



      Servers use a    variety    of conventions for designating CGI
      scripts as NPH.  Many    Unix servers look at the beginning of
      the script's name for    the prefix "nph-".  The    Macintosh
      WebSTAR server and Microsoft's Internet Information Server,
      in contrast, try to decide whether a program is an NPH
      script by examining the first    line of    script output.

      CGI.pm supports NPH scripts with a special NPH mode.    When
      in this mode,    CGI.pm will output the necessary extra header
      information when the _h_e_a_d_e_r()    and _r_e_d_i_r_e_c_t() methods are
      called.

      The Microsoft    Internet Information Server requires NPH mode.
      As of    version    2.30, CGI.pm will automatically    detect when
      the script is    running    under IIS and put itself into this
      mode.     You do    not need to do this manually, although it
      won't    hurt anything if you do.

      There    are a number of    ways to    put CGI.pm into    NPH mode:

      In the uuuusssseeee statement
          Simply add the "-nph"    pragmato the list of symbols
          to be    imported into your script:

            use CGI    qw(:standard -nph)


      By calling the nnnnpppphhhh(((()))) method:
          Call nnnnpppphhhh(((()))) with a non-zero parameter at any point
          after    using CGI.pm in    your program.

            CGI->nph(1)


     statements:
      By using ----nnnnpppphhhh    parameters in the hhhheeeeaaaaddddeeeerrrr(((()))) and rrrreeeeddddiiiirrrreeeecccctttt(((())))

            print $q->header(-nph=>1);


     SSSSeeeerrrrvvvveeeerrrr PPPPuuuusssshhhh
      CGI.pm provides three    simple functions for producing
      multipart documents of the type needed to implement server
      push.     These functions were graciously provided by Ed    Jordan
      <[e-mail]>.  To    import these into your namespace, you
      must import the ":push" set.    You are    also advised to    put
      the script into NPH mode and to set $| to 1 to avoid
      buffering problems.

      Here is a simple script that demonstrates server push:





     Page 49                        (printed 10/23/98)






     CCCCGGGGIIII((((3333))))         22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))        CCCCGGGGIIII((((3333))))



        #!/usr/local/bin/perl
        use    CGI qw/:push -nph/;
        $| = 1;
        print multipart_init(-boundary=>'----------------here we go!');
        while (1) {
        print multipart_start(-type=>'text/plain'),
              "The current time    is ",scalar(localtime),"\n",
              multipart_end;
        sleep 1;
        }

      This script initializes server push by calling
      mmmmuuuullllttttiiiippppaaaarrrrtttt____iiiinnnniiiitttt(((()))).  It    then enters an infinite    loop in    which
      it begins a new multipart section by calling
      mmmmuuuullllttttiiiippppaaaarrrrtttt____ssssttttaaaarrrrtttt(((()))), prints the    current    local time, and    ends a
      multipart section with mmmmuuuullllttttiiiippppaaaarrrrtttt____eeeennnndddd(((()))).  It then sleeps a
      second, and begins again.

      multipart_init()       multipart_init(-boundary=>$boundary);
          Initialize the multipart system.  The    -boundary
          argument specifies what MIME boundary    string to use
          to separate parts of the document.  If not provided,
          CGI.pm chooses a reasonable boundary for you.

      multipart_start()

            multipart_start(-type=>$type)

          Start    a new part of the multipart document using the
          specified MIME type.    If not specified, text/html is
          assumed.

      multipart_end()

            multipart_end()

          End a    part.  You must    remember to call
          _m_u_l_t_i_p_a_r_t__e_n_d() once for each    _m_u_l_t_i_p_a_r_t__s_t_a_r_t().

          Users    interested in server push applications should
          also have a look at the CGI::Push module.

     AAAAvvvvooooiiiiddddiiiinnnngggg DDDDeeeennnniiiiaaaallll ooooffff    SSSSeeeerrrrvvvviiiicccceeee    AAAAttttttttaaaacccckkkkssss
      A potential problem with CGI.pm is that, by default, it
      attempts to process form POSTings no matter how large    they
      are.    A wily hacker could attack your    site by    sending    a CGI
      script a huge    POST of    many megabytes.     CGI.pm    will attempt
      to read the entire POST into a variable, growing hugely in
      size until it    runs out of memory.  While the script attempts
      to allocate the memory the system may    slow down
      dramatically.     This is a form    of denial of service attack.




     Page 50                        (printed 10/23/98)






     CCCCGGGGIIII((((3333))))         22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))        CCCCGGGGIIII((((3333))))



      Another possible attack is for the remote user to force
      CGI.pm to accept a huge file upload.    CGI.pm will accept the
      upload and store it in a temporary directory even if your
      script doesn't expect    to receive an uploaded file.  CGI.pm
      will delete the file automatically when it terminates, but
      in the meantime the remote user may have filled up the
      server's disk    space, causing problems    for other programs.

      The best way to avoid    denial of service attacks is to    limit
      the amount of    memory,    CPU time and disk space    that CGI
      scripts can use.  Some Web servers come with built-in
      facilities to    accomplish this. In other cases, you can use
      the shell _l_i_m_i_t or _u_l_i_m_i_t commands to    put ceilings on    CGI
      resource usage.

      CGI.pm also has some simple built-in protections against
      denial of service attacks, but you must activate them    before
      you can use them.  These take    the form of two    global
      variables in the CGI name space:

      $$$$CCCCGGGGIIII::::::::PPPPOOOOSSSSTTTT____MMMMAAAAXXXX
          If set to a non-negative integer, this variable puts
          a ceiling on the size    of POSTings, in    bytes.    If
          CGI.pm detects a POST    that is    greater    than the
          ceiling, it will immediately exit with an error
          message.  This value will affect both    ordinary POSTs
          and multipart    POSTs, meaning that it limits the
          maximum size of file uploads as well.     You should
          set this to a    reasonably high    value, such as 1
          megabyte.

      $$$$CCCCGGGGIIII::::::::DDDDIIIISSSSAAAABBBBLLLLEEEE____UUUUPPPPLLLLOOOOAAAADDDDSSSS
          If set to a non-zero value, this will    disable    file
          uploads completely.  Other fill-out form values will
          work as usual.

          You can use these variables in either    of two ways.

      1111.... OOOOnnnn    aaaa ssssccccrrrriiiipppptttt----bbbbyyyy----ssssccccrrrriiiipppptttt bbbbaaaassssiiiissss
          Set the variable at the top of the script, right
          after    the "use" statement:

              use CGI qw/:standard/;
              use CGI::Carp 'fatalsToBrowser';
              $CGI::POST_MAX=1024 * 100;  # max    100K posts
              $CGI::DISABLE_UPLOADS = 1;  # no uploads


      2222.... GGGGlllloooobbbbaaaallllllllyyyy ffffoooorrrr aaaallllllll ssssccccrrrriiiippppttttssss
          Open up CGI.pm, find the definitions for $POST_MAX
          and $DISABLE_UPLOADS,    and set    them to    the desired
          values.  You'll find them towards the    top of the



     Page 51                        (printed 10/23/98)






     CCCCGGGGIIII((((3333))))         22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))        CCCCGGGGIIII((((3333))))



          file in a subroutine named _i_n_i_t_i_a_l_i_z_e__g_l_o_b_a_l_s().

          Since    an attempt to send a POST larger than
          $POST_MAX bytes will cause a fatal error, you    might
          want to use CGI::Carp    to echo    the fatal error
          message to the browser window    as shown in the
          example above.  Otherwise the    remote user will see
          only a generic "Internal Server" error message.  See
          the the _C_G_I::_C_a_r_p manpage manual page    for more
          details.

     CCCCOOOOMMMMPPPPAAAATTTTIIIIBBBBIIIILLLLIIIITTTTYYYY WWWWIIIITTTTHHHH    CCCCGGGGIIII----LLLLIIIIBBBB....PPPPLLLL
      To make it easier to port existing programs that use cgi-
      lib.pl the compatibility routine "ReadParse" is provided.
      Porting is simple:

      OLD VERSION
          require "cgi-lib.pl";
          &ReadParse;
          print "The value of the antique is $in{antique}.\n";

      NEW VERSION
          use CGI;
          CGI::ReadParse
          print "The value of the antique is $in{antique}.\n";

      CGI.pm's _R_e_a_d_P_a_r_s_e() routine creates a tied variable named
      %in, which can be accessed to    obtain the query variables.
      Like ReadParse, you can also provide your own    variable.
      Infrequently used features of    ReadParse, such    as the
      creation of @in and $in variables, are not supported.

      Once you use ReadParse, you can retrieve the query object
      itself this way:

          $q = $in{CGI};
          print $q->textfield(-name=>'wow',
                  -value=>'does    this really work?');

      This allows you to start using the more interesting features
      of CGI.pm without rewriting your old scripts from scratch.

     AAAAUUUUTTTTHHHHOOOORRRR IIIINNNNFFFFOOOORRRRMMMMAAAATTTTIIIIOOOONNNN
      Copyright 1995-1997, Lincoln D. Stein.  All rights reserved.
      It may be used and modified freely, but I do request that
      this copyright notice    remain attached    to the file.  You may
      modify this module as    you wish, but if you redistribute a
      modified version, please attach a note listing the
      modifications    you have made.

      Address bug reports and comments to:
      [e-mail]



     Page 52                        (printed 10/23/98)






     CCCCGGGGIIII((((3333))))         22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))        CCCCGGGGIIII((((3333))))



     CCCCRRRREEEEDDDDIIIITTTTSSSS
      Thanks very much to:

      Matt Heffron ([e-mail])

      James    Taylor ([e-mail])

      Scott    Anguish    <[e-mail]>

      Mike Jewell ([e-mail])

      Timothy Shimmin ([e-mail])

      Joergen Haegg    ([e-mail])

      Laurent Delfosse ([e-mail])

      Richard Resnick ([e-mail])

      Craig    Bishop ([e-mail])

      Tony Curtis ([e-mail])

      Tim Bunce ([e-mail])

      Tom Christiansen ([e-mail])

      Andreas Koenig ([e-mail])

      Tim MacKenzie    ([e-mail])

      Kevin    B. Hendricks ([e-mail])

      Stephen Dahmen ([e-mail])

      Ed Jordan ([e-mail])

      David    Alan Pisoni ([e-mail])

      Doug MacEachern ([e-mail])

      Robin    Houston    ([e-mail])

      ...and many many more...
          for suggestions and bug fixes.

     AAAA CCCCOOOOMMMMPPPPLLLLEEEETTTTEEEE    EEEEXXXXAAAAMMMMPPPPLLLLEEEE    OOOOFFFF AAAA SSSSIIIIMMMMPPPPLLLLEEEE FFFFOOOORRRRMMMM----BBBBAAAASSSSEEEEDDDD SSSSCCCCRRRRIIIIPPPPTTTT
          #!/usr/local/bin/perl

          use CGI;

          $query = new CGI;



     Page 53                        (printed 10/23/98)






     CCCCGGGGIIII((((3333))))         22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))        CCCCGGGGIIII((((3333))))


























































     Page 54                        (printed 10/23/98)






     CCCCGGGGIIII((((3333))))         22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))        CCCCGGGGIIII((((3333))))



          print    $query->header;
          print    $query->start_html("Example CGI.pm Form");
          print    "<H1> Example CGI.pm Form</H1>\n";
          &print_prompt($query);
          &do_work($query);
          &print_tail;
          print    $query->end_html;

          sub print_prompt {
             my($query)    = @_;

             print $query->startform;
             print "<EM>What's your name?</EM><BR>";
             print $query->textfield('name');
             print $query->checkbox('Not my real name');

             print "<P><EM>Where can you find English Sparrows?</EM><BR>";
             print $query->checkbox_group(
                       -name=>'Sparrow locations',
                       -values=>[England,France,Spain,Asia,Hoboken],
                       -linebreak=>'yes',
                       -defaults=>[England,Asia]);

             print "<P><EM>How far can they fly?</EM><BR>",
              $query->radio_group(
                  -name=>'how far',
                  -values=>['10    ft','1 mile','10 miles','real far'],
                  -default=>'1 mile');

             print "<P><EM>What's your favorite    color?</EM>  ";
             print $query->popup_menu(-name=>'Color',
                          -values=>['black','brown','red','yellow'],
                          -default=>'red');

             print $query->hidden('Reference','Monty Python and    the Holy Grail');

             print "<P><EM>What    have you got there?</EM><BR>";
             print $query->scrolling_list(
                   -name=>'possessions',
                   -values=>['A    Coconut','A Grail','An Icon',
                         'A    Sword','A Ticket'],
                   -size=>5,
                   -multiple=>'true');

             print "<P><EM>Any parting comments?</EM><BR>";
             print $query->textarea(-name=>'Comments',
                        -rows=>10,
                        -columns=>50);

             print "<P>",$query->reset;
             print $query->submit('Action','Shout');
             print $query->submit('Action','Scream');



     Page 55                        (printed 10/23/98)






     CCCCGGGGIIII((((3333))))         22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))        CCCCGGGGIIII((((3333))))



             print $query->endform;
             print "<HR>\n";
          }

          sub do_work {
             my($query)    = @_;
             my(@values,$key);

             print "<H2>Here are the current settings in this form</H2>";

             foreach $key ($query->param) {
            print "<STRONG>$key</STRONG> ->    ";
            @values    = $query->param($key);
            print join(", ",@values),"<BR>\n";
            }
          }

          sub print_tail {
             print <<END;
          <HR>
          <ADDRESS>Lincoln D. Stein</ADDRESS><BR>
          <A HREF="/">Home Page</A>
          END
          }


     BBBBUUUUGGGGSSSS
      This module has grown    large and monolithic.  Furthermore
      it's doing many things, such as handling URLs, parsing CGI
      input, writing HTML, etc., that are also done    in the LWP
      modules. It should be    discarded in favor of the CGI::*
      modules, but somehow I continue to work on it.

      Note that the    code is    truly contorted    in order to avoid
      spurious warnings when programs are run with the ----wwww switch.

     SSSSEEEEEEEE AAAALLLLSSSSOOOO
      the _C_G_I::_C_a_r_p    manpage, the _U_R_I::_U_R_L manpage, the
      _C_G_I::_R_e_q_u_e_s_t manpage,    the _C_G_I::_M_i_n_i_S_v_r manpage, the
      _C_G_I::_B_a_s_e manpage, the _C_G_I::_F_o_r_m manpage, the    _C_G_I::_A_p_a_c_h_e
      manpage, the _C_G_I::_S_w_i_t_c_h manpage, the    _C_G_I::_P_u_s_h manpage, the
      _C_G_I::_F_a_s_t manpage













     Page 56                        (printed 10/23/98)






     CCCCGGGGIIII((((3333))))         22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))        CCCCGGGGIIII((((3333))))























































     Page 57                        (printed 10/23/98)